DEV Community: Meticulosity

Your MCP server's real constraint is the context window, not the API

Meticulosity — Tue, 04 Aug 2026 13:00:00 +0000

We use AskElephant to record client calls, and we work in claude.ai. Those two things could not talk to each other, and the reason is structural rather than a missing feature.

AskElephant ships an MCP server. It runs locally over stdio, which serves Claude Desktop, Cursor, VS Code and Windsurf. A browser cannot spawn a process on your laptop, so claude.ai needs an MCP server at an HTTPS address. That is a different program.

Building it took about a day. Working out what it should refuse to do took considerably longer, and that part generalises to any MCP server sitting in front of a large corpus. The code is on GitHub.

The arithmetic that determines the design

Before writing tools, measure your payload. We measured every transcript in our account: 3,706 engagements, 2,230 of which carry one.

	Characters	Approx tokens
Average transcript-bearing call	32,485	8,100
Median	28,240	7,060
p95	75,543	18,885
Largest	175,643	43,900

The largest single call is more than a fifth of a 200,000-token context window on its own.

Now consider the actual user request: "find where we discussed pricing with this client this year." That touches maybe forty calls. The naive tool returns forty transcripts, which is roughly 325,000 tokens. It does not fit. Not slow, not costly: impossible.

So the design constraint is not the API. It is arithmetic, and it arrives before you write a single tool definition.

Do the reading on the server

The whole design collapses to one line:

The Worker does the reading. Claude does the thinking.

search_transcripts fetches the candidate transcripts, scans them inside the Worker, and returns only matching passages with speaker and timestamp attached. A real forty-meeting search, run through claude.ai against the live archive, returned 76,757 characters of excerpt: about 19,200 tokens rather than 325,000.

The scanner is a pure function with no IO, which makes it trivial to test:

export function scanTranscript(
  text: string,
  queries: string[],
  opts: ScanOptions = {},
): Hit[]

Transcript lines arrive as [0:03:15] Speaker Name: utterance, so matching per line rather than per character means every hit carries its own timestamp and speaker for free. Excerpt windows snap outward to line boundaries, so an excerpt never begins mid-sentence.

Two details that matter more than they look:

Match literally, never by regex. Query terms come from a language model, and a model will happily emit 5.00 or C++. Building a RegExp from that input is both a correctness bug and an injection hazard. A test pins it: 5.00 must not match 5x00.

Keep offsets against the raw string. The chunked transcript reader slices the cached text by the offsets the scanner produced. We later stripped carriage returns from excerpt output, and the only safe way to do that was in the returned text, never by normalising the source, because normalising shifts every index. The test asserts both that the excerpt is clean and that the offset still points into the unmodified string.

The bug worth stealing: limits multiply

We had three limits, each defensible on its own:

max_meetings: 40
max_hits_per_meeting: 10
context_chars: 2000

Each is validated independently. Nothing validated their product, which measured at about 229,000 tokens. The caps existed to protect a 200,000-token window and their worst case overran it.

Two things compounded it. Excerpts snap outward to line boundaries, so a request for 2,000 characters yields about 2,297. And there is no overlap dedup, so ten hits inside one dense passage return substantially the same text ten times.

The fix is a single budget across the whole run, in config rather than scattered through the code:

searchOutputCharBudget: 120000,   // about 30,000 tokens

Enforced with one accumulator, admitting hits one at a time, and stopping the fetch loop entirely once spent. Critically, the response says which happened:

Scanned 12 meeting(s). Results were CUT FOR SIZE at the output budget.

A caller must be able to tell a cut for size from a cut for relevance. They mean opposite things and look identical if you do not say.

The bug worth stealing more: silence is not absence

Originally, a failed transcript fetch was logged and skipped. Nothing about the failure reached the return value.

Play that forward. The API key gets rotated. All forty fetches 401. The tool answers:

Scanned 40 meeting(s). No matches. Try different phrasings in queries, or widen the date range.

A person reading that concludes the topic was never discussed. That is worse than an error, because an error is obviously an error. This is a confident wrong answer with a suggestion attached.

The fix is counting, and reporting:

{ scanned: 40, failed: 40, no_transcript: 0, results: [] }

and rendering "40 could not be read" instead of "No matches". If your tool can return an empty result for more than one reason, it has to say which reason.

Five API behaviours that each cost us a bug

AskElephant's v2 API is not publicly documented. Every one of these was found by probing, and most were found only because something already broke.

0. Some transcripts contain the same call twice. Listed first because it is the one that survived everything else. The transcript field can hold the whole call, an attachment marker, then a character-for-character second copy:

[0:00:25] Alice: Hi, Bob.
... the entire call ...
[0:29:08] Bob: See ya.
[Attachment eatt_01KYAH5JQ4C31VVE2PE797AP69: Bot Recording]
[0:00:25] Alice: Hi, Bob.
... the entire call again, identical ...

Measured on the call that exposed it: 59,088 characters, opening line recurring at offset 29,575, second segment identical across all 29,513 of its characters. The reliable signature is a backward jump in timestamps — the transcript runs to 0:29:08 and the next line is 0:00:25.

Search was therefore finding every match twice, paying the output budget for each passage twice, and filling the per-meeting hit cap with duplicates. The fix drops a segment that exactly repeats one already kept, and preserves near-duplicates and genuinely different second recordings, because losing a real utterance is far worse than wasting characters.

There is a second, sharper lesson in how we sized it. The first measurement said half the corpus was affected. It was taken over the transcripts the Worker had cached — which are the meetings our searches happened to touch, skewing recent, internal and bot-recorded, exactly the population that duplicates. Measuring your cache measures your query history. Re-measuring all 2,230 transcripts put it at 5.8%, about a million wasted tokens archive-wide.

1. The auth header takes the raw key, no Bearer prefix. Cheap to fix, easy to lose an hour to.

2. processing_status is PENDING on every record ever created, including calls from 2023. We had built the initial filter around COMPLETED, which returns zero rows for everything. Transcript availability actually tracks engagement_type: calendar entries never carry one.

3. search matches titles only, never transcript bodies. This is the reason the excerpt scanner exists at all. We got this wrong twice. First we assumed it searched bodies. Then we "verified" titles-only using the words pricing, leadership and onboarding, which are exactly the words that also appear in meeting titles, so the evidence was consistent with both behaviours and distinguished neither. The proof that worked was a phrase spoken mid-call that appears nowhere in the title, run against a 2023 call so that index lag could not explain a miss.

4. Filters need operators, and dates need full UTC. filter[company_ids]=<id> returns 400; it needs filter[company_ids][in]. And filter[start_at][gte]=2026-01-01 returns 400 too:

must be an ISO8601 UTC date (e.g. 2025-01-01T00:00:00.000Z)

Both shapes came from our own earlier notes and neither had been sent to the live API. The tool now widens a bare YYYY-MM-DD itself, to start of day for a lower bound and end of day for an upper bound, because a model asked for "this year" will emit the plain form every time.

The pattern across all five: the plan described the API, and nobody had asked the API. If you take one process change from this post, make it a step that probes every request shape you actually send, once, before you trust it — and then a second step that runs the finished thing against real data, because number 0 passed every review gate and fell out of the first real question a human asked.

What Cloudflare gave us

@cloudflare/workers-oauth-provider handles the part everyone gets stuck on. Claude.ai initiates OAuth 2.1 with Dynamic Client Registration, and this library makes the Worker its own OAuth server while delegating the actual login upstream, in our case to Cloudflare Access over OIDC with PKCE.

export default new OAuthProvider({
  apiRoute: "/mcp",
  apiHandler: McpAskElephant.serve("/mcp"),
  defaultHandler: { fetch: accessHandler },
  authorizeEndpoint: "/authorize",
  tokenEndpoint: "/token",
  clientRegistrationEndpoint: "/register",
});

McpAgent handles Streamable HTTP and session state on a Durable Object. KV caches transcripts, which are immutable once processed, with a TTL, because a cache without one is a permanent second copy of client data living outside the vendor's retention controls.

One operational trap worth knowing. Each scanned meeting costs about three subrequests, so the default of 25 meetings costs roughly 76. The free plan caps at 50, so a free-tier deployment breaks at about 15 meetings, not at the 40 the config implies. The paid plan allows 1,000.

The security thing I got wrong in public

We first restricted access by email domain, reasoning that revocation could be delegated upstream: everyone uses a company-controlled Claude account, so deprovisioning that account takes the connector with it.

That reasoning is wrong, and we proved it by accident. The connector can be attached to any Claude account, including a personal one, because the only identity the Worker ever sees is the Cloudflare Access identity. Our own testing left two separate Claude clients registered against one address.

Access is now an explicit list of named individuals. And because removing someone from that list only stops them getting a new grant, there is a script that deletes an existing one, since a grant in KV outlives any config change until it expires.

If you are building anything similar: work out what your revocation story actually is, then test it, rather than reasoning about it.

Worth saying about the process

This was built with Claude Code, task by task, with a separate review pass on each one that had no attachment to the code it was reviewing.

The interesting part is where the defects came from. Almost all of the real ones originated in the plan, not the implementation: the filter shape, the date format, a row limit applied per search term so a two-term query could return double what was asked for, and a hand-written type for a contact's email field that disagreed with the API while agreeing perfectly with the test fixture invented alongside it.

The implementations were mostly faithful. The specification was confidently wrong in four places. That ratio is the argument for adversarial review, and it is not the argument the tooling vendors usually make.

Repo, with setup instructions for your own deployment: github.com/meticulosity-dward/askelephant-mcp

Nine things I measured about the HubSpot API that the docs don't tell you

Meticulosity — Mon, 03 Aug 2026 04:04:16 +0000

I spent a day building a read-only tool that answers one question about a HubSpot portal: what is the cheapest tier its current usage actually requires?

Everything below was probed with GET requests against a live portal on 2 August 2026. Where it contradicts HubSpot's documentation, trust this. The tool is open source and MIT licensed: meticulosity/hubspot-license-fit.

1. The API cannot tell you what a portal is subscribed to

This is the constraint the whole design hangs off, so it is worth establishing first.

GET /account-info/v3/details

{"portalId": 0000000, "accountType": "STANDARD", "timeZone": "...",
 "companyCurrency": "USD", "additionalCurrencies": ["CAD", "SAR"],
 "dataHostingLocation": "na1", "uiDomain": "app.hubspot.com"}

No subscription object, no tier field, no entitlement list. accountType describes the kind of account, not the tier purchased.

So a tool cannot report what somebody pays. It can only work backwards from evidence: three custom objects exist, therefore some Enterprise subscription is in play. That is a floor, not a verdict, and the difference matters because the second one is a claim about a contract you cannot see.

2. You cannot introspect a private app token

HubSpot documents GET /oauth/v1/access-tokens/{token} for checking a token's scopes. It does not work for private app tokens, which is what everyone actually uses:

Attempt	Result
`GET /oauth/v1/access-tokens/{pat-token}`	400 `The access token must have the correct format`
`GET /oauth/v2/access-tokens/{pat-token}`	404
`GET /oauth/v1/private-apps/access-tokens/{pat-token}`	404

That endpoint is for OAuth access tokens. A pat-na1-... token has no introspection path at all.

The design consequence is the interesting bit. My original plan was "on startup, check the token's scopes and refuse to run if any of them can write." That is unimplementable. So the guarantee had to move from their configuration to my code: one function that builds every request and refuses anything that is not a GET, plus a test that greps the source.

def _request(self, method, path, params=None):
    if method != "GET":
        raise ReadOnlyViolation(
            "this tool issues GET requests only, refused: %s %s" % (method, path))

WRITE_VERBS = re.compile(r"""["']\s*(POST|PATCH|PUT|DELETE)\s*["']""")

def test_no_write_verb_appears_in_any_source_file():
    offenders = [...]  # scan every .py in the package
    assert offenders == []

It is a weaker promise in one sense and a much stronger one in another. I cannot verify what your token is allowed to do. I can verify that I never try.

3. A 403 never tells you which scope is missing

Four different scope failures, four identical response bodies:

{"status":"error",
 "message":"This app hasn't been granted all required scopes to make this call.
            Read more about required scopes here: https://developers.hubspot.com/scopes.",
 "correlationId":"..."}

If you want to tell a user which scope to grant, you carry your own endpoint-to-scope mapping. There is nothing in the response to parse.

4. A 403 and a zero are different answers, and conflating them is dangerous

Obvious when written down, easy to get wrong in code. GET /settings/v3/users/teams returned 403 on a portal that plainly had five teams.

If your model has two states (found / not found), that 403 collapses into "no teams." For a tool whose output influences whether somebody downgrades a subscription, that is the one error that costs a user a feature they were relying on.

So the gate model has three states, and the third never renders as the second:

FIRES   = "fires"    # something requires a tier
CLEAR   = "clear"    # read successfully, not present
UNKNOWN = "unknown"  # could not read, so nothing is claimed

5. The workflow list endpoint returned 0 flows, then 113

Same token, seconds apart:

GET /automation/v4/flows  ->  {"results": []}
GET /automation/v4/flows  ->  {"results": [ ...113 flows... ]}

It paginates via paging.next.after and it is flaky. A tool that trusts one unpaginated call will confidently report "no workflows found" on a portal running a hundred of them, which is worse than crashing because it looks like an answer.

Paginate, and retry an empty first page before believing it:

if pages == 0 and not page and retry_empty_first_page and not retried_empty:
    retried_empty = True
    time.sleep(self.pause * 4)
    continue

GET /automation/v4/flows/{id} is reliable. Only the list misbehaves. (/automation/v3/workflows returns a different, smaller set: 82 against 113. It is not a substitute.)

6. HubSpot ships its own calculated properties into every portal

Calculated properties are a paid-tier feature, so "does any property carry a calculation formula?" looks like a reasonable gate check.

It is not. On the portal I tested, 21 contact properties carried calculationFormula, and all 21 had hubspotDefined: true. days_to_close and friends ship everywhere, including free portals. User-created calculated properties: one.

with_formula = [p for p in rows if p.get("calculationFormula")]
user_formula = [p for p in with_formula if not p.get("hubspotDefined")]

Only the second list means anything. Without that filter the tool fires a paid-tier claim on every portal in existence.

7. Association labels have the same trap

GET /crm/v4/associations/contacts/companies/labels

[{"category": "HUBSPOT_DEFINED", "label": "Primary"},
 {"category": "HUBSPOT_DEFINED", "label": "Billing Contact"},
 {"category": "USER_DEFINED",    "label": "Renewal Owner"}]

Every portal ships the HUBSPOT_DEFINED ones. Filter on category == "USER_DEFINED".

The general lesson, which cost me two near-misses in one afternoon: when a platform seeds default data, presence of a thing is not evidence that somebody chose the thing. Check provenance, not existence.

8. Three refusals that can be routed around

A 403 or a 404 on the obvious endpoint does not always mean the answer is unavailable. It sometimes means you are asking the wrong endpoint.

Teams: 403. But GET /crm/v3/owners returns a teams array per owner, and /settings/v3/users returns primaryTeamId and secondaryTeamIds. Five named teams were readable while the teams endpoint itself refused.

Business units: 404 on /business-units/v3/user/. But GET /marketing/v3/emails carries businessUnitId per email, and six of 112 emails sat on a non-default unit. That answers the question the direct endpoint would not.

Sequences: 400. GET /automation/v4/sequences returns query param userId may not be null. Sequences are per user. Pass ?userId=N and sample users until one has some.

When you route around, say so in the output. My reports print "5 teams in use, read from owner records, because the teams endpoint was refused," because a reader deserves to know which source answered.

9. Some HubSpot scopes have no read-only variant

This one changed the product, not just the code.

content, external_integrations.forms.access, and behavioral_events.event_definitions.read_write are all offered only as combined read-and-write scopes.

For a diagnostic tool the implication is uncomfortable: reading marketing emails, forms, or custom behavioral events requires asking the user to grant write access to their portal. I decided not to. Those checks report as unreadable with that as the stated reason, and the tool's scope list contains read-only scopes exclusively.

Same reasoning killed one more signal. GET /crm/v3/lists/search returns 405: it is a POST with a body. Since the entire promise is that the codebase contains no write verbs, I dropped list counts rather than carve out an exception. Losing a signal was cheaper than losing the property that makes the guarantee testable.

The thing I would tell myself at the start

Write down which of your findings are observations and which are claims, and keep them in separate parts of the output.

Counts read from an API are facts. They stay true. Statements like "custom objects require Enterprise" are claims about a vendor's packaging, and vendors move packaging: HubSpot's own catalogue now puts Enterprise deal pipelines at 100 per account where my older reference data said 50.

So every tier claim in the output carries the date it was verified, and the table expires itself after 60 days, downgrading everything to "unverified, confirm before quoting." The counts never get downgraded, because they never went stale.

Full source, the fixtures, and the complete measurement log are in the repo: meticulosity/hubspot-license-fit. It is Python with no dependencies, and python3 -m license_fit --dry-run renders a full sample report without a token or a network call.