|
| 1 | +--- |
| 2 | +date_created: 2026-06-21 |
| 3 | +date_modified: 2026-06-21 |
| 4 | +title: "Decile Hub connector — augment-it's first per-client API integration, built from the OpenAPI spec out" |
| 5 | +lede: "A VC client runs their fund + CRM on Decile Hub. Tonight augment-it learns to talk to it — a skill that codifies the contract and a TypeScript MCP server that exposes it as agent tools, both grounded in Decile's own OpenAPI spec rather than guesswork. It's the first connector in the per-client seam we've been building toward." |
| 6 | +publish: true |
| 7 | +authors: |
| 8 | + - Michael Staton |
| 9 | +augmented_with: |
| 10 | + - Claude Code on Claude Opus 4.8 (1M context) |
| 11 | +files_changed: |
| 12 | + - services/decile-mcp/src/client.ts |
| 13 | + - services/decile-mcp/src/server.ts |
| 14 | + - services/decile-mcp/package.json |
| 15 | + - services/decile-mcp/tsconfig.json |
| 16 | + - services/decile-mcp/README.md |
| 17 | + - context-v/specs/Workspaces-as-Tenant-Primitive.md |
| 18 | + - clients/humain-vc/README.md |
| 19 | +tags: |
| 20 | + - Augment-It |
| 21 | + - Decile-Hub |
| 22 | + - Connector |
| 23 | + - MCP |
| 24 | + - Per-Client |
| 25 | + - CRM |
| 26 | + - OpenAPI |
| 27 | + - Agent-Skill |
| 28 | + - Humain-VC |
| 29 | + - SurrealDB |
| 30 | +--- |
| 31 | + |
| 32 | +# Decile Hub connector — the first per-client API integration |
| 33 | + |
| 34 | +## Why Care? |
| 35 | + |
| 36 | +For months the workspace architecture has promised something it hadn't yet delivered: that |
| 37 | +each VC client could bring their *own* tools — their own CRM, their own data — and augment-it |
| 38 | +would talk to whichever one the active workspace uses, without one client's integration |
| 39 | +leaking into another's. The [[Workspaces-as-Tenant-Primitive|connector seam]] was built; the |
| 40 | +worked example (Decile) was a placeholder with a fake `.example` URL. |
| 41 | + |
| 42 | +Tonight it's real. **Humain VC runs on [Decile Hub](https://decilehub.com)** — a venture |
| 43 | +fund-management + CRM platform — and augment-it can now pull and push their people, |
| 44 | +organizations, pipeline prospects, and notes. Two artifacts make it work: a **skill** that |
| 45 | +codifies how Decile's API behaves, and a **TypeScript MCP server** that turns that contract |
| 46 | +into tools an agent can call. Both are built from Decile's **own OpenAPI spec** — not from |
| 47 | +training-data guesses about what their endpoints probably look like. |
| 48 | + |
| 49 | +This is the first of what will be many per-client connectors. Getting the *first* one right — |
| 50 | +grounded, isolated, mapped cleanly onto our canonical layer — sets the pattern for the rest. |
| 51 | + |
| 52 | +## What's New? |
| 53 | + |
| 54 | +- **`decile-hub-connector` skill** (authored in the lossless-agent-skills repo, live via |
| 55 | + symlink) — the operating guide: auth, base URL, the data shapes, how to pull, how to push, |
| 56 | + and how Decile records map onto our SurrealDB `persons` / `organizations`. Plus a |
| 57 | + `references/endpoint-inventory.md` listing every endpoint. |
| 58 | +- **`services/decile-mcp/`** — a TypeScript MCP server exposing the CRM-core operations as |
| 59 | + tools (`decile_whoami`, list/get/upsert person & organization, notes, pipelines, prospects). |
| 60 | + Builds clean (`tsc`); register with `claude mcp add -s project`. |
| 61 | +- **Env-var reconciliation** — the spec + the humain-vc README anticipated |
| 62 | + `DECILE_API_BASE_URL` / `DECILE_API_KEY` / `DECILE_TENANT_ID`. The real, working vars are |
| 63 | + `DECILE_API_URL` + `DECILE_HUB_API_KEY` (the tenant is in the subdomain, so there's no |
| 64 | + separate tenant id). Both docs now match reality. |
| 65 | + |
| 66 | +## How It Works |
| 67 | + |
| 68 | +### The contract, confirmed from the spec — not guessed |
| 69 | + |
| 70 | +The single most important discipline here: **a connector skill is only useful if its |
| 71 | +endpoints are real.** So everything below was read out of Decile's 11,970-line OpenAPI spec |
| 72 | +(saved at `clients/humain-vc/inputs/decilehub/202506_decilehub-docs_swagger.yaml`), and the |
| 73 | +extraction caught several things memory would have gotten wrong: |
| 74 | + |
| 75 | +| Thing | Reality | |
| 76 | +|---|---| |
| 77 | +| **Auth** | `Authorization: <token>` — the **raw** API token, **no `Bearer`** (one stale doc example showed Bearer; the scheme is a plain apiKey header) | |
| 78 | +| **Base URL** | `https://<tenant>.decilehub.com` — **per-tenant subdomain** (humain → `humain.decilehub.com`); routes under `/api/v1/` | |
| 79 | +| **Pagination** | **three** different patterns — 0-indexed `{data, pagination}`, 1-indexed `{key, page, per_page, total}`, and keyset `{data, pagination:{next_page_token, has_more}}` | |
| 80 | +| **Writes** | upsert-by-natural-key — `POST /person` (by email), `POST /organization` (by name) — returning a `changes` diff | |
| 81 | +| **Errors** | mostly `{error:{code,message,field,…}}`, but a few endpoints return a bare `{error:"string"}` | |
| 82 | + |
| 83 | +The MCP's client (`src/client.ts`) encodes all of this: raw-token auth, a helper per |
| 84 | +pagination pattern, and a `normalizeError` that handles both error shapes. |
| 85 | + |
| 86 | +### It maps onto the canonical layer we already have |
| 87 | + |
| 88 | +Decile is a per-client *source*, so everything it feeds into our canonical layer carries the |
| 89 | +client tag (per [[Client-Tagging-on-Canonical-Writes]]). The mapping is natural: Decile |
| 90 | +people → `persons` (join on email), organizations → `organizations` (join on name/slug). And |
| 91 | +Decile's own upsert-by-natural-key semantics mirror our SurrealDB upsert discipline almost |
| 92 | +exactly — SELECT-by-key, then merge-or-create. |
| 93 | + |
| 94 | +### Two surfaces, one contract |
| 95 | + |
| 96 | +The skill and the MCP are complementary: the skill is the human/agent-readable *guide* and the |
| 97 | +source of truth for the mapping; the MCP is the *executable* layer. The spec marks |
| 98 | +agent-facing operations with `x-agent-tool: true` — those are the tools the server exposes |
| 99 | +first; the rest follow the identical `server.tool(...) → client` pattern. |
| 100 | + |
| 101 | +## Under The Hood |
| 102 | + |
| 103 | +The whole thing is tenant-agnostic by design. `src/client.ts` reads `DECILE_API_URL` + |
| 104 | +`DECILE_HUB_API_KEY` from the environment — nothing about Humain is hard-coded — so a second |
| 105 | +VC client on Decile is just a second registration with that client's subdomain and token. The |
| 106 | +per-client `.env` (resolved through the workspace seam) is where the tenant lives, exactly as |
| 107 | +[[Workspaces-as-Tenant-Primitive]] intended. |
| 108 | + |
| 109 | +Extraction was done by reading the spec in full and pulling out the complete endpoint |
| 110 | +inventory + the CRM resource shapes, so the skill's reference doc is exhaustive rather than a |
| 111 | +sampling. When the next endpoints are needed (deal shares, deal memos, portfolio companies, |
| 112 | +tasks, files, events), they're a few lines each against the existing client. |
| 113 | + |
| 114 | +## Files Changed |
| 115 | + |
| 116 | +- `services/decile-mcp/` — new MCP server (`client.ts`, `server.ts`, `package.json`, `tsconfig.json`, `README.md`) |
| 117 | +- `context-v/specs/Workspaces-as-Tenant-Primitive.md` — Decile worked example updated to the real env vars (bumped to `0.0.0.2`) |
| 118 | +- `clients/humain-vc/README.md` — secrets list updated to `DECILE_API_URL` + `DECILE_HUB_API_KEY` *(submodule)* |
| 119 | +- `decile-hub-connector` skill — authored in the lossless-agent-skills repo (separate repo; live via symlink) |
| 120 | + |
| 121 | +## What's Next |
| 122 | + |
| 123 | +- Register the MCP for the humain-vc tenant and confirm with `decile_whoami`. |
| 124 | +- Wire a Decile → SurrealDB sync that pulls people/organizations into the canonical layer, client-tagged, treating Decile as one provenance `source`. |
| 125 | +- Extend the tool set beyond the CRM core as workflows demand it. |
| 126 | + |
| 127 | +## See Also |
| 128 | + |
| 129 | +- [[Workspaces-as-Tenant-Primitive]] — the per-client connector seam this is the first real instance of |
| 130 | +- [[Connecting-To-And-Using-SurrealDB]] — the canonical-layer connection + client-tagging contract Decile data flows into |
| 131 | +- [[2026-06-21_01_Corpus-Meets-Its-Org-Content-Items-Ledger-And-The-Publisher-About-Mentions-Model]] — the same day's canonical-layer work |
0 commit comments