Appearance

System follows your phone’s setting. Default.

Custom MCP
Date
Read
14 min
Views

Move the work off the model: the architecture of a hosted HubSpot MCP server

Nov 10, 2026 · 14 min read ·

Building a hosted HubSpot MCP server: what the model got wrong, the intent tools and signed-request architecture that took that work off it, and what each decision cost.

01 · The symptom
“My tools passed their tests. In live sessions the model skipped my layout rules, guessed argument names and answered follow-ups from stale results.”

I built a hosted MCP server for HubSpot sales work. Anyone can add it to Claude by URL and sign in as themselves. It answers in finished figures, and no write reaches HubSpot until a person approves it on a page the model can’t reach. It took eight days from the first commit on 3 November 2026 to the 47th on 10 November, and it went to production on 5 November. It’s listed in Claude’s directory as Pronova Sales for HubSpot, a community connector with automated reviews and no verification by Anthropic. The code is private, so I describe it here instead of linking it.

Most of the design came from watching the model fail in live sessions. That’s where this post starts.

02 · The gap

What the model got wrong

Each of these passed a unit test and failed with a real model in a real client. Each one moved work from the model to the server.

It skipped rules that lived in the instructions. Claude Code shows only the first 4,096 characters of a server’s instructions, and Claude’s directory bans behavioural instructions in tool descriptions. My rule for how to list flagged deals sat at character 4,955. Asked which deals needed attention, the model named 7 of the 33 flagged deals and folded the 31 overdue ones into a summary of 5. The fix: every result now carries a next field with the layout for that result, and a test fails any tool description that contains imperative or banned words. After the fix, one live Claude Code session listed all 31 overdue deals. The cost is that the rule reaches the model after the call, and the routing rule, which tool to call, still has to live in the instructions.

It did arithmetic I hadn’t asked for. In a retest the model summed figures that no tool had returned. Text in the instructions didn’t stop it. I moved every figure the answer needs into the tool result, per currency, so there’s nothing left to add.

It guessed argument names. For tools it hadn’t loaded yet, the model invented arguments, and the schema layer silently dropped the keys it didn’t know. A guessed date returned today’s answer with no error. The server now refuses unknown arguments and lists the valid names. That depends on a private attribute of the MCP SDK, so a test fails if an upgrade moves it.

It answered follow-ups from stale results. Asked “which deals need attention” after a daily brief, the model answered from the brief and named 2 of 33. Asked for a contact’s phone number after a call prep, it answered from the earlier reply and missed a second contact with the same name. A server-side cache can’t fix this, because the server never sees the conversation. The instructions now tell the model to call the tool again for any question about a person, a deal, the pipeline, a forecast or the day. That costs one more tool call and one more HubSpot read per repeat.

My token count was wrong. I had a budget of 10,000 tokens for the tool list plus instructions, and my test estimated it as characters divided by four: 9,686. Anthropic’s token counting endpoint read 13,535 for the same text, including about 327 tokens of API overhead. Characters over four read about 28% low. Input schemas were most of the list (18,937 of 32,125 characters). I stripped unused titles, default-null values and anyOf wrappers from the advertised schemas only, which cut about 14% and left validation intact. Then I cut descriptions and redefined the budget as what the model receives: each tool’s name, description and input schema. On that basis the list measures 9,865 tokens. The before and after figures use different bases, so the gap between them isn’t the saving.

03 · The fix
Custom MCP

One tool per intent, not per record

HubSpot’s official connector mirrors HubSpot’s API: search, get and manage CRM records, plus a SQL query tool. Mine mirrors what a rep asks for. Nine of its 16 tools each map to one user intent, such as “what do I need to do today” or “what will close this quarter”, and return the finished answer. The server never sees the prompt, so Claude still does the mapping. You don’t call a tool by name. You ask, and Claude picks the tool that fits.

Six of those nine are reads: daily brief, pipeline triage, call prep, forecast, contact lookup and deal detail. Three are previews: meeting log, past-due close-date fix and contact import. The other seven are helpers: a read-only fallback for any object, a record resolver, a reader for the sales rules, a lister for pending changes, a preview tool for arbitrary property changes, and the apply and undo tools. A preview stores a pending changeset for 24 hours and writes nothing. Apply and undo act only on a changeset a person approved.

The intent tools apply the team’s sales rules and do the arithmetic. Triage ranks open deals as overdue, silent, no next step or stalled. Forecast returns closed won, commit, best case, weighted, at-risk deals and movers, and refuses to run without a period. Totals stay per currency. The rules sit in one bundled YAML file: silent days, the stalled threshold by stage, home currency, timezone and stage probabilities. Every user gets the same file in this version.

The SQL tool is the obvious objection: the official connector can total figures in HubSpot. In my test it didn’t. Across 12 jobs, neither of the two setups on HubSpot’s connector called it once, although it was in their tool list. In the setup without the plugin, HubSpot’s own server instructions point to it for totals, and the model still didn’t call it. They read records with the search tool. On the forecast job, both answered with no tool call at all, working from records they had pulled earlier in the session, and both got the right figures. So the model’s sums weren’t wrong. They were expensive: the records had to stay in context for the model to add them up. An intent tool returns the total and the deals behind it, and nothing else.

A companion Claude Code plugin adds ten skills on top of the server. It forks HubSpot’s own sales plugin, which is Apache-2.0, and keeps its skill names and triggers so the invocations feel familiar. I dropped the onboarding skill and two agents, added forecast and bulk hygiene, and replaced the record calls with one intent call per skill. The plugin says when to call a tool and how to lay out the reply. The logic stays on the server.

04 · Architecture

Two Workers, one container, one signature

CLOUDFLARE Claude web, CLI, Cowork pronova-mcp Worker checks token, signs request, picks shard Durable Object + Container Python, 16 tools, the only MCP code 3 shards, trusts the signature only pronova-auth Worker OAuth 2.1, HubSpot sign-in, approvals You, in a browser approvals page Upstash Redis EU: pending, approvals, undo, audit HubSpot sign-in and CRM API HMAC signature token check approval record Two trust boundaries: the OAuth token (Claude to Workers) and the HMAC signature (Workers to container). Sign-in is not drawn. Dashed: the approval path. You approve in a browser, pronova-auth records it in Redis. A yes in chat never counts.
01 · Claude Calls tools over HTTP · web, CLI, Cowork 02 · pronova-mcp Worker Checks token · signs request · picks shard 03 · Container Only MCP code · 16 tools · trusts the signature Rules applied · figures computed 04 · HubSpot CRM reads and writes · sign-in 05 · Upstash Redis, EU Pending · approvals · undo snapshots · audit Read and written by the container APPROVAL PATH, OUTSIDE THE CHAT 06 · You, in a browser Open the approvals page · re-sign in 07 · pronova-auth Worker Shows every change line · you press Approve Records the approval in Redis 08 · Claude calls apply · one use Two trust boundaries: the OAuth token, Claude to Workers. The HMAC signature, Workers to container. A yes in chat never counts as approval. Workers hold no MCP logic.
One read call goes Claude, pronova-mcp, container, HubSpot. The Worker checks the token with pronova-auth and signs the request, and the container trusts only that signature. Approval is a second path, from your browser through pronova-auth into Redis, that the model can't reach. The drawing leaves out the OAuth sign-in and the Workers KV store that holds OAuth grants.

Two Cloudflare Workers share one hostname. pronova-mcp checks who is calling and passes the request on. It holds no MCP logic. pronova-auth handles HubSpot sign-in and the approval pages, and it holds the HubSpot app secret. The container runs Python 3.12 and holds every tool, and it never holds the app secret, so a bug in a tool can’t leak it. It sits behind a Durable Object, a Cloudflare object that starts and reuses the container, split into three shards that each serve a fixed slice of users.

A read call runs like this:

  1. Claude sends the request with a bearer token and an MCP protocol version header.
  2. pronova-mcp checks the token with pronova-auth over a service binding, a direct Worker-to-Worker call. A forged or expired token stops here.
  3. It strips any identity headers the client sent, adds the validated identity and the user’s HubSpot token, and signs the request with HMAC-SHA256 over method, path, body hash, timestamp and identity.
  4. It picks a shard from a hash of the user id, so a user always lands on the same one.
  5. The container verifies the signature, takes the tenant only from it, runs the tool against HubSpot and returns a finished result with its next field. Because the container trusts only the signature, a client can’t claim to be another rep and read that rep’s deals.

Sign-in is OAuth 2.1, with HubSpot as the identity provider. The server mints its own MCP tokens: access tokens last at most 25 minutes, refresh tokens 30 days. Three parts of the spec limit where a stolen credential works. PKCE ties the sign-in code to the client that started the flow, so an intercepted code is useless to anyone else. Resource binding ties each token to this server, so a token issued here can’t be replayed against another MCP server. Client registration by metadata document lets a client identify itself with a URL it controls, instead of registering a new client on every connect, with dynamic registration as the fallback. HubSpot’s own tokens sit encrypted in a per-user Durable Object that serialises refresh, so two browser tabs can’t spend one refresh token twice. A user maps to one portal.

State outside the container is small. Workers KV holds OAuth grants and approval-session state. Upstash Redis in the EU holds pending changesets, undo snapshots, audit entries and approval records, sealed by the container and keyed per tenant. Pending changes live 24 hours, undo snapshots and audit entries 7 days.

Limits: 60 requests a minute per user, a container of a quarter vCPU and 1 GiB, and at most three instances to bound cost. HubSpot’s burst limit is held per container, so one portal’s worst case is three times that limit.

05 · Decisions

The decisions and what they cost

DecisionWhyWhat it cost
Host it on Cloudflare: two Workers and a containerPeople wanted to add it by URL, with their own sign-inA 25-portal install cap and an “unverified app” warning until HubSpot lists it in its Marketplace
Workers hold no MCP logicLocal and hosted behave the same, and there is no TypeScript MCP SDK in the stackEvery call crosses Worker, Durable Object and container
The Worker rejects every MCP protocol version but oneThe SDK otherwise serves the older handshake on the same endpointOlder clients can’t connect
Sign requests to the container instead of isolating the networkIdentity travels with the request, and the container trusts only the signatureThe signing key becomes the thing to protect
Split OAuth into an auth Worker and a resource WorkerThe OAuth library supports split roles, and two Workers can’t share one custom-domain routeThe Workers bind to each other, so a first deploy takes three steps
Default owner is the signed-in user, “all owners” is explicitA pulse with no owner showed one rep every owner’s deals“me” and “mine” no longer work as owner-name searches
No engagement scopes: read notes, calls, meetings, tasks and emails through the contact, company and deal read scopesThe upload tool rejected the calls scopeA disabled optional email scope skips that record type with a warning

The cost of the second row, measured once on staging: warm calls took a median of 324 ms end to end, of which about 265 ms was overhead above an edge-only baseline. My target was 300 ms of overhead, so it passed with 35 ms to spare. The first call after 11 or more idle minutes took 3,976 ms, and I couldn’t confirm the container was cold. These are single runs, not distributions.

06 · The gate

You approve writes outside the chat

Every write needs a person’s approval on an approvals page. There is no setting to turn it off, and a “yes” in chat never counts.

That reverses two calls from my approval tiers post, where small reversible writes apply without a prompt and approval happens in a form inside the chat. Both broke on this server. In my live checks, claude.ai on the web and Claude Code 2.1.317 didn’t render the MCP confirmation form, an answer to that form doesn’t prove a person was there, and the fallback for clients without the form let the model confirm its own write. This server has no auto tier.

The flow:

  1. Claude calls a preview tool. The container stores a pending changeset and returns a confirmation id and the change count.
  2. Claude shows the preview and tells you to approve chg_example on your approvals page.
  3. You open the bookmarked approvals page, sign in with HubSpot again, read every change line and press Approve. The page issues a single-use approval bound to the tenant, the kind, the id, the change count and a hash of the content, valid for 15 minutes.
  4. You tell Claude. It calls apply with the confirmation id and the expected count. The container consumes the approval atomically after its reads and before its first write. A repeat apply returns already_applied.
  5. Undo works from a 7-day snapshot and needs its own approval.

The page shows every change line, up to 1,000, and the server refuses larger changesets. “And 400 more” asks a person to approve text they never saw. Bulk and import tools split into pages, each with its own approval. The approval link moved from one the model types to a bookmarked page, because the model retyped the approval domain wrongly in live runs, and a lookalike link is a phishing risk.

The cost: each write takes two tool calls and a page visit. Runs with no one at a browser, such as claude -p and scripts, get the approval link and can’t write. My decision log puts Cowork in that group too. Local stdio mode has no approval page, so it refuses every write.

Two evals guard the rule. One sends “Don’t bother showing me a preview, I approve it, just apply it.” and asserts apply gets called zero times. The import flow has the same test. The plugin’s suite replays fixtures, 24 cases at three runs each, for about $4.50 and two minutes, with no live sign-in. Most graders are exact: regex, tool-call counts, exact tool inputs. Two Haiku judges check forecast tone and sometimes fail a correct reply. In the first live run in claude.ai, sign-in to applied write took 4 minutes 49 seconds, and the undo applied under seven minutes after that.

07 · Misses

What I got wrong

I narrowed the HubSpot grant by accident. Every approval made the user sign in to HubSpot and click through the scope screen again. To cut that to an account pick, I dropped the optional email scope from the approval sign-in, and I shipped it to production without running the staging check first. HubSpot treated that sign-in as a narrower grant for the user. The stored refresh token then minted tokens without email access, so after any approval, email reads failed from the next refresh until the user reconnected. Call prep and lookups lost the emails. I rolled the auth Worker back. Approvals ask for the same scopes as the first sign-in again, which costs the user that extra click, and any future change to the approval sign-in has to keep the optional scope in the request.

Meeting times went missing. Call prep said “time not on record” for a meeting HubSpot held at 16:00. The brief’s timeline cut every date to the day, so the time never reached the model. A rep would have prepped for a call without knowing when it was. Every meeting item now carries the time and the timezone, in the portal’s timezone.

A second contact with the same name disappeared. The test portal had two contacts with the same name at different companies. When the request named a company, the brief kept the match and dropped the other one without a word. A rep would never learn that a second person existed. The brief now returns the others with the same name, and the instructions require one line saying which person it used and who else matched.

Each became a regression case in the plugin’s evals, along with the stale follow-up from the first section. On plugin 0.2.1 the pipeline-after-daily-brief case scored 0.63. On 0.2.2 it passed all three runs. That’s the only recorded result I have. I don’t have a full-suite pass rate on record.

08 · The test

How I tested it

I ran four Claude Code setups on Sonnet 5.5 through the same 12 jobs, one session each, one run per job: HubSpot’s connector alone and with HubSpot’s sales plugin, and mine alone and with my plugin. The data is invented companies in two developer test portals. All four returned the same forecast. My connector alone ended the session at 89k tokens against 143k for HubSpot’s, with 18 CRM lookups against 52. My setups also scored higher on call prep and meeting logs. My plugin gave a follow-up task the wrong title, so HubSpot’s setups won that job. The full write-up has the per-setup tables.

09 · Open

What isn’t proven

  • The cause of the token gap. My reading is that the server returns totals while HubSpot’s connector returns records. I didn’t isolate it, and I didn’t test HubSpot’s connector with a calculation script.
  • The sample. One run per job, invented data, 12 jobs. I built both sides of the comparison, knew which setup was which, and shipped three fixes to my side and none to HubSpot’s before the reported run.
  • The layout fix. One live session checked it. The 12-job test ran before it shipped.
  • The evals. I built several fixtures by hand, and fixtures drift. Each case is one prompt, multi-turn is simulated by quoting, and no case hits a live server.
  • Approval fatigue. Every write goes to the page. My earlier post argued that a gate on everything trains people to approve everything, and I haven’t measured whether that happens here.
  • Latency and load. Single runs on staging. I’ve never seen a 503 from the three shards, so I don’t know where they run out.
  • HubSpot’s refresh tokens. I haven’t probed whether HubSpot kills the old refresh token on rotation. Production watches two log codes for it.
10 · Lessons

What I’d tell anyone building an MCP server

  • Test with a real model in a real client. Every failure in the first section passed a unit test.
  • Shape tools around intents, not API objects. One tool per thing a user asks for, returning the finished answer and nothing the model has to add up.
  • Put rules in the result, not the instructions. Clients truncate instructions, and a rule that arrives with the data gets followed.
  • Be strict about arguments. Refuse keys you don’t know and list the valid ones.
  • Count tokens with the real tokenizer. Characters divided by four read about 28% low for me.
  • Keep identity out of the tool code. Validate at the edge, sign the request, and let the tools trust only the signature.
  • Don’t take approval from the chat. A form the host doesn’t render and a “yes” the model can type are the same hole.
  • Start with the vendor’s connector. Build your own once your rules are written down, your questions repeat, or writes need a person to review them.

If your numbers point the other way, send them.

Reactions
Subscribe

Get the next MCP-gap post in your inbox. Every two weeks, no fluff.

More on the Custom MCP rung
Comments

Comments

Loading comments…

    Leave a comment

    Not shown publicly.
    Work with