---
slug: mcp-as-a-projection
title: "MCP is one view of a capability table, and the view you pick costs 6.25x"
kind: essay
status: published
hash: c872f49b99caa78bc3b3b38c573ecc7802fc64ad230f42b5970b2972a035f639
created: 2026-07-26T03:52:52.299Z
updated: 2026-10-08T11:33:09.673Z
summary: "One recorded 891-capability catalogue published three ways — zero definitions, seven tools, or 856 tools — cost 6.25× more per turn through its largest surface; live wire measurements show the moving counts."
tags: ["tooling","mcp","architecture","json-rpc","tool-cost","protocol"]
above: []
below: []
adjacent: []
nested: []
---
# MCP is one view of a capability table, and the view you pick costs 6.25x

*One recorded 891-capability catalogue published three ways — zero definitions, seven tools, or 856 tools — cost 6.25× more per turn through its largest surface; live wire measurements show the moving counts.*

The Model Context Protocol (MCP) is a way of *describing* a set of capabilities to a model. It is not the place those capabilities live, and it is not the thing that runs them. On this site the capabilities live in one database table — one row per capability — and MCP is one of three ways that table is shown to a model.

**Scope note:** this page measures one thing well — what it costs to show *this* catalogue to a model three different ways. It is not a claim that the catalogue is the architecture. [892 rows, 8 of them MCP](/a/the-directory-is-not-the-object-system) breaks the same table down by runner and category and shows MCP is 8 of the 891 rows measured here, not the subject the table exists to serve.

A **projection** here means exactly one thing: a view generated from a table, holding nothing of its own. Change the table and every view changes in the same instant. Delete a view and nothing is lost. Below, the plainer word **surface** is used wherever it reads more clearly; they mean the same thing.

The three surfaces reach the same capability catalogue. The recorded benchmark puts 6.25× between the cheapest and the dearest turn.

```widget
{
  "type": "source",
  "id": "m1"
}
```

## Evidence status

**Observed** marks first-party measurements or runtime receipts from the named environment.
**Derived** marks arithmetic calculated from cited inputs. **Specified** marks vendor or standards
documentation. **Implemented** and **deployed** name code and live-state evidence, respectively.
**Reproduced** means the stated procedure was rerun. **Externally attested** marks operator reports;
those reports show that an experience occurred, not that it is universal.

## MCP at the wire is JSON-RPC 2.0, one of two transports, and a handful of method names

A reader who has never opened the specification can hold the whole thing in one paragraph. A client and a server exchange JSON-RPC 2.0 messages. JSON-RPC is a remote-procedure-call format: a JSON object carrying `jsonrpc`, `method`, `params` and `id`, answered by an object carrying the same `id` and either `result` or `error`. The specification is blunt about this: *"MCP uses JSON-RPC to encode messages. JSON-RPC messages **MUST** be UTF-8 encoded."*

Those messages travel over one of two transports. Standard input and output, for a server running as a local subprocess. Or HTTP POST, for a server running somewhere else — the specification calls the second one Streamable HTTP and requires that *"Every JSON-RPC message sent from the client **MUST** be a new HTTP POST request to the MCP endpoint."* It also states a preference: *"Clients **SHOULD** support stdio whenever possible."*

The method names that matter for a capability catalogue are four:

| Method | Direction | What it carries | What this site's server returns |
| --- | --- | --- | --- |
| `initialize` | client → server | protocol version, client capabilities | `protocolVersion: "2025-06-18"`, `capabilities: {"tools":{"listChanged":false}}`, `serverInfo` |
| `tools/list` | client → server | nothing, or a pagination cursor | an array of `{name, description, inputSchema}` — 831 of them, measured below |
| `tools/call` | client → server | `params.name`, `params.arguments` | `{content:[{type:"text",text:"…"}], isError:false}` |
| `notifications/tools/list_changed` | server → client | nothing | never sent — this server declares `listChanged: false` |

A tool definition is three fields: a name, a description in prose, and a JSON Schema for the arguments. That triple is what lands in the model's context window. Everything expensive about MCP follows from the size of that triple multiplied by the number of tools.

### What MCP is not

- **Not a wire protocol.** The layering claim gets used to wave away responsibility, and it is wrong. JSON-RPC is the wire protocol; MCP sits above it.
- **Not a place capabilities live.** A server holds handlers. Nothing in the specification says where the list of capabilities is stored, or that it must be a hand-written list at all.
- **Not a rule about context loading.** The tools specification says implementations *"are free to expose tools through any interface pattern that suits their needs—the protocol itself does not mandate any specific user interaction model."* Every token figure quoted below is a property of a client, not of the protocol.
- **Not a replacement for an API.** It is a second face on one. The endpoint stays; MCP is a decorated index in front of it.

## One recorded 891-row catalogue cost 6.25× more through its largest surface

The table holds 891 rows — 876 objects answered the live registry today, and the drift is explained under the measurements. Each row is a full capability contract: key, runner, target, documentation, input schema, authority flags. [What a directory row is](/a/directory-row-contract) covers the row itself; [891 tools, zero tool schemas](/a/tooling-as-data) covers why a catalogue is better held as data than as code.

| Surface | Tool definitions in the model's context | What the model can reach | What the client must support | Measured input tokens per turn | Measured cost per turn | What breaks |
| --- | --- | --- | --- | --- | --- | --- |
| **Protocol only** — `POST /api/dispatch` | 0. The 9 definitions present are the client's own built-ins | all 891 rows | an HTTP client. No MCP, no tool calling at all | 14,071 | $0.00456265 | the model must be told four endpoints once; no client UI enumerates the catalogue |
| **Small surface** — `workers/mcp-server` | 7 tools, whatever the catalogue size | all 891 rows, through the `dispatch` tool | an MCP client | not measured | not measured | a client that lists tools shows seven generic entries; discovery becomes a call, not context |
| **Per-row MCP** — `POST /api/mcp` | 831 measured today, 856 recorded | 831 rows, each a named tool | an MCP client | 149,187 | $0.02852109 | prompt cost, tool-selection accuracy, and strict-schema clients rejecting the whole list |
| **Per-row MCP, tool search on** | 9 plus a `ToolSearch` tool | all 891, loaded on demand | a client with deferred tool loading | 14,109 | $0.00443075 | the deferred index does not cover every server — two filed bugs below |

The arithmetic between the first and third rows: 149,187 − 14,071 = **135,116 input tokens burned per turn** holding definitions the turn mostly does not use. 149,187 ÷ 14,071 = **10.6× the input tokens**. $0.02852109 ÷ $0.00456265 = **6.25× the money**. Across a thousand turns that gap is **$23.96**. The token ratio and the money ratio differ because output tokens are in both bills and the cache behaves differently; both are the recorded gateway figures, not a rate derived from one of them.

```widget
{
  "type": "source",
  "id": "m2"
}
```

## Each surface is a file, and the file states its own tool count

**Per-row MCP** is `functions/api/mcp.js`, 189 lines. Lines 118–137 are the entire projection:

```js
const r = await env.DB.prepare(
  'SELECT key, type, category, content, input_schema FROM directory ' +
  'WHERE IFNULL(enabled,1)=1 AND IFNULL(planner_visible,1)=1 ' +
  'ORDER BY IFNULL(planner_rank,100), key'
).all();
```

One row becomes one tool: `name` is the row key, `description` is the first documentation line plus `[type · category]`, `inputSchema` is the row's schema after normalisation. Line 162 is the whole `tools/list` handler. Lines 80–116 exist for one reason worth stating plainly: Moonshot and Kimi clients validate every schema strictly and reject the **entire** tool list on the first violation, so one legacy row with a `required` name missing from `properties` would blank the catalogue for that client. Claude Code tolerates both, which is how the bad schemas accumulated unnoticed.

**Small surface** is `workers/mcp-server/src/index.ts`, 138 lines, a Cloudflare `McpAgent` on a Durable Object. It registers seven tools, lines 19–105:

```
$ grep -A1 'this.server.tool($' workers/mcp-server/src/index.ts | grep '"'
      "d1_query",
      "kv_get",
      "kv_put",
      "list_directory",
      "dispatch",
      "oip_registry",
      "oip_invocations",
```

Seven, not six. An earlier record of this surface counted six by folding `kv_get` and `kv_put` into one line and omitting `d1_query`. The file is the authority and the file says seven. The invariant is the point either way: **seven tools whether the table holds 9 rows or 9,000**, because `dispatch` takes `{key, body}` and the key space is the table. All seven parameter descriptions together come to 429 characters of source.

**Protocol only** is `functions/api/dispatch.js`. No tool definitions are published anywhere. A model that can make an HTTP request resolves an intent, reads a contract, invokes it, and reads a receipt — four calls, set out in [Resolve, read, invoke, receipt](/a/dispatch-four-step-loop).

## Measured today: 831 definitions occupied 434,636 bytes on the wire

Two first-party measurements, both rerunnable. `MCP_TOKEN` is the server's bearer token; `/api/mcp` accepts it in `Authorization` or in `x-mcp-token`.

**Measurement 1 — count the per-row surface.**

```bash
curl -s -X POST https://miscsubjects.com/api/mcp \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' -o tl.json \
  -w "http=%{http_code} bytes=%{size_download} time=%{time_total}s\n"

python3 -c "import json;t=json.load(open('tl.json'))['result']['tools'];print(len(t), len(json.dumps(t)))"
```

Three readings on 2026-07-26:

| Reading (UTC) | Tools | JSON bytes | What was counted | Wall time |
| --- | --- | --- | --- | --- |
| 04:37:06Z | 833 | 452,157 | Python re-serialization with spaces | not recorded |
| 04:39:08Z | 831 | 451,197 | Python re-serialization with spaces | 0.60 s |
| 05:03:04Z | 831 | 434,636 | exact HTTP response body | 0.267 s |

The HTTP body contains 434,592 bytes of compact tool definitions plus the 44-byte JSON-RPC wrapper. Python's default `json.dumps` adds spaces after separators, which is why the command above reports 451,197 for the same 831 definitions. Both numbers are reproducible; **434,636 is the network payload**.

Where the 451,197-character Python serialization goes, computed from the same file:

| Component of the tool list | Characters | Share |
| --- | --- | --- |
| Descriptions — first doc line plus `[type · category]` | 200,757 | 44.5% |
| Input schemas, after normalisation | 189,354 | 42.0% |
| Tool names | 13,862 | 3.1% |
| JSON structure and quoting | 47,224 | 10.5% |

Compact average per tool: **523 bytes**. Largest single definition in the spaced Python serialization: `CF_OBSERVABILITY_QUERY_WORKER_OBSERVABILITY` at 6,511 bytes. By runner type the 831 split into 462 `fn`, 301 `http`, 50 `flow`, 18 `agent`.

Three counts for the same server now exist on this page — 856 recorded, 833 at 04:37, 831 at 04:39 — and each is correct for its moment. Rows get added, disabled (`enabled = 0`) and hidden (`planner_visible = 0`) while the site runs, and only enabled plus planner-visible rows are projected. A tool count taken from an MCP server is a reading, not a constant. The 891 total and the 856 projection were taken on 2026-07-25.

**Measurement 2 — show that zero definitions still reaches everything.**

```bash
curl -s "https://miscsubjects.com/api/dispatch?registry=1" -o reg.json \
  -w "http=%{http_code} bytes=%{size_download} time=%{time_total}s\n"
python3 -c "import json;print(json.load(open('reg.json'))['count'])"

curl -s "https://miscsubjects.com/api/dispatch?ask=send%20an%20email" | head -c 400
```

Result at 05:03:04Z: `http=200 bytes=1606794 time=0.397555s`, and `876` objects. The resolver call returned `{"protocol":"OIP","version":"1.2.0","kind":"ask","question":"send an email","count":12,"best":{"key":"EMAIL_SEND", …}}` in 14,481 bytes — twelve candidate capabilities ranked, one recommended, none of it resident in a prompt. Nothing was registered with a model. No tool definition was loaded. All 876 objects are invokable by key.

```widget
{
  "type": "source",
  "id": "m3"
}
```

## The case for shipping an MCP surface, at its strongest

The deflationary reading — MCP is a REST API with extra steps — is usually stated by people who then keep using it. **CharlieDigital**, whose team built one, put the deflation and the recommendation in a single sentence: *"MCP is effectively \"just another HTTP REST API\"; OAuth and everything. The key parts of the protocol is the communication shape and sequence with the client, which most SDKs abstract for you"*. Deploying one is no harder than deploying the API underneath it, because the SDK writes the transport.

**brookst** gave the sharpest rebuttal of the just-HTTP framing: *"It's like saying APIs are dead because you can just use HTTP. They're not the same thing, though of course you can hand-roll the higher layer in the lower one. It's just more work, less standard, less valuable."* A decorated index of features beats a bare endpoint list, and the decoration is the product.

**menix** argues the contract itself is the value rather than a nicety. Input and output schemas let a code-writing agent plan one precise program instead of a print-and-inspect loop, and *"Tool results from programmatic calls are not added to Claude's context window, only the final code output is. They report up to 98.7% token savings in some workflows."*

**827a** supplies the dissent every measurement below has to survive: *"The idea that MCP tool definitions take up a certain number of tokens is laughable. That's an implementation detail of the agent harness."* This is correct as written, and the specification agrees — nothing in MCP says a client must paste all definitions into a prompt. The measurements are of clients. They still decide the bill, because those are the clients that exist.

There is an audience argument too. **oortcrate_1** prefers a bash wrapper personally and still grants the point: MCP serves non-technical teammates who want a connection that works without filing a pull request.

## The case against, with the numbers the complainants actually measured

| Who | What they measured | Verdict |
| --- | --- | --- |
| moltar | *"Right now loading GitHub MCP takes something like 50k tokens."* | reduces MCP to "an API with docs"; wants progressive reveal |
| gertjandewilde (Apideck) | *"tool definitions alone burned 50,000+ tokens before the agent touched a single user message"* | replaced the server with a CLI at ~80 tokens; cites a 75-run comparison at 4–32× overhead |
| yonatangross | *"The main agent context burns 16.9k tokens (8.5% of 200k) loading 68 MCP tool schemas at session start. Most are never called by the main agent"* | publishes a per-server table; scoping and tool search were available and unused |
| abdlkrim-jribi | *"The agent injects ALL 47 tool schemas on every single request, consuming ~13,341 tokens before the user message is even sent."* | audits his own agent; publishes the ~4,168 / ~4,515 / ~751 / ~3,906 split |
| mjlee | *"With a handful of third party MCPs I've seen tens of thousands of tokens used before I've started anything."* | finds MCP beneficial anyway |
| 0xbadcafebee | *"Say each tool is 150 tokens, that's 150 * 50, or 7500 tokens, dumped into the beginning of every session."* | the balanced account — shell one-liners are more non-deterministic, so re-runs pollute context too; uses both |
| locknitpicker | *"Skills effectively turned MCPs obsolete in the vast majority of MCP applications."* | a progressive-disclosure CLI needs no skill file at all |
| noodletheworld | *"MCP is just \"me too\"; people want MCP to be an \"AI App Store\"; but the blunt, harsh reality is that it's basically impossible to achieve that dream"* | if you want an app, build an app |

Two mitigations get proposed against all of this, and both have filed defects. **cheema33** pre-empts the first: *"And no, the tool search function recently introduced by Anthropic does not completely solve this problem."* Anthropic's own documentation puts that mitigation at *"over 85 percent"* reduction on a five-server setup consuming *"~55k tokens in definitions before Claude does any work"* — real, and not total. **sophiabits** names the second-order cost of the other mitigation, loading servers lazily per task: *"The main problem with this approach at the moment is it busts your prompt cache, because LLMs expect all tool definitions to be defined at the beginning of the context window."*

Deferred loading has its own failure modes on record. In `anthropics/claude-code#57033`, servers added at claude.ai show Connected in `/mcp` and yet *"Any `ToolSearch` query that should match a claude.ai MCP tool returns zero results"*. In `openai/codex#24536`, *"`codex exec` can silently finish with no assistant message when an explicitly configured MCP tool is deferred behind `tool_search`."* A silent empty turn is worse than an expensive one.

```widget
{
  "type": "source",
  "id": "m4"
}
```

## Round trips are the argument that survives bigger context windows

Token cost is a moving target. Context windows grow, caches improve, tool search lands. The structural argument does not move, and it is a different argument.

A tool call happens **between** completions. The model stops, the client executes, the result comes back, the model starts again. **DonHopkins** names the difference: *"I call this \"speed of light\" as opposed to \"carrier pigeon\"."* Code the model writes loops, recurses and composes **inside** one generation.

**martinald** gives the worked case — summing 150 order IDs. *"With MCP the agent would have to do 150 tool calls and explode your context."* One scripted loop does it in one round trip at roughly one percent of the tokens. He also notes there is no reason a harness could not expose MCP tools inside a sandboxed code environment, and that nobody does.

Two vendors have published the same finding independently. Anthropic: *"This reduces the token usage from 150,000 tokens to 2,000 tokens—a time and cost saving of 98.7%."* Cloudflare, on the same pattern: *"With the traditional approach, the output of each tool call must feed into the LLM's neural network, just to be copied over to the inputs of the next call, wasting time, energy, and tokens. When the LLM can write code, it can skip all that, and only read back the final results it needs."*

What that implies for exposing a catalogue is concrete, and it is not "abandon MCP":

1. Expose **one invoking tool that takes a key and arguments**, not one tool per capability. That is what the seven-tool surface does.
2. Make discovery a **call that returns data** — `list_directory`, or the protocol's resolver — so the catalogue is paged through rather than resident.
3. Keep an **HTTP path a code-execution sandbox can hit directly**, so a loop over 150 items is one round trip instead of 150.

**solarkraft** supplies the honest floor under all three: every capability costs some context, because the model has to know it exists in order to invoke it. The only question is whether it costs 523 compact bytes each or one line in a search result.

## `notifications/tools/list_changed` is in the specification, and named clients ignore it

The advertised benefit of a server-side catalogue is that adding a capability needs no client redeploy. The specification supplies the mechanism: *"When the list of available tools changes, servers that declared the `listChanged` capability **SHOULD** send a notification"* — `notifications/tools/list_changed`, a JSON-RPC notification with no parameters and no reply.

Whether that works depends on the client honouring it, and three filed reports say several do not:

| Client or system | Filed | Verbatim |
| --- | --- | --- |
| Kiro IDE — `kirodotdev/Kiro#6553`, closed | 2026-03-20 | *"When an MCP server dynamically adds or removes tools at runtime and sends this notification per the MCP spec, Kiro IDE does not re-query tools/list, so the new tools never appear until the server is manually reconnected."* |
| GitHub Copilot CLI — `microsoft/wassette#308`, open | 2025-09-29 | *"Internal terminal testing shows the CLI never refreshes its tool list, unlike GitHub Copilot in VS Code which updates immediately."* |
| MCPJungle gateway — `mcpjungle/MCPJungle#260`, open | 2026-05-15 | *"MCPJungle caches upstream tool lists at registration time only. If an upstream server adds or removes tools later, MCPJungle's view stays stale until a manual re-registration or full restart."* |

The wassette report comes from a Microsoft engineer with a reproduction video, and notes the same server updates immediately in VS Code — so the defect is per-client, not per-spec.

This site's per-row server sidesteps the question by declaring the truth instead of a promise. Line 159 of `functions/api/mcp.js` returns `capabilities: {"tools":{"listChanged":false}}`. A new row is live on the protocol surface the instant it is written, and appears on the MCP surface the next time a client calls `tools/list` — which, for most clients, is at connect. **"Add a capability without a redeploy" is true of the table and false of the client.** Say the second half out loud or the sentence is a lie.

## Verdict: publish MCP when the client is not yours, publish the protocol when it is

- **Do publish an MCP surface** when the consumer is a client you do not control and cannot teach — Claude Desktop, Cursor, ChatGPT connectors, a colleague's IDE. There is no other way in. Publish it as a **small surface**: one `dispatch`-style tool plus a discovery tool. Never one tool per row.
- **Do publish a per-row surface** only when a client must literally see named tools in its own interface, and only with that client's deferred loading switched on. Otherwise expect the bill: 149,187 input tokens and $0.02852109 per turn, measured.
- **Do not put MCP in front of your own agent** when you already control the harness. The protocol surface reached all 891 capabilities at 14,071 input tokens and $0.00456265 per turn, with nine tool definitions in context — all nine of them the client's built-ins.
- **Do not treat MCP as the architecture.** It is a view. The table is the thing.

**What would change this verdict.** A mainstream client that fetches definitions on demand rather than at connect, and honours `notifications/tools/list_changed`, would collapse the per-row surface's cost to roughly the protocol's and remove the reason to hand-build a small surface. Anthropic's tool search is the first move in that direction and already reaches 14,109 tokens on this catalogue — within 0.3% of the protocol-only figure. Two filed bugs, `claude-code#57033` and `codex#24536`, say it is not yet reliable enough to depend on. When those close and the behaviour is the default rather than a flag, publish per-row and stop hand-rolling.

## Publish the same catalogue three ways

Cheapest surface first, because it is also the one that works everywhere.

**A. Protocol only — no server to write.** Prerequisite: a capability table with a key, a runner, a target, a documentation field and an input schema (see [the row contract](/a/directory-row-contract)), plus one HTTP handler that looks a key up and runs it.

1. `GET /api/dispatch` returns a manifest naming the verbs and endpoint shapes. It was 17,404 bytes at 05:06:05Z.
2. `GET /api/dispatch?ask=<intent>` returns ranked candidates, each with an `example`, an `example_args` and a ready `run_now` URL.
3. `GET /api/dispatch?key=<KEY>&format=markdown` returns the exact row contract.
4. `POST /api/dispatch` with `{"key":"KEY","body":"args"}` invokes it. Add `"shape": true` for a dry run that returns the fully-shaped outbound payload without firing.
5. `GET /api/dispatch?receipt=<id>` returns the receipt.

Run the read-only `TIME_NOW` path end to end:

```bash
export TERMINAL_KEY="<owner access key>"

curl -sS "https://miscsubjects.com/api/dispatch?ask=what%20time%20is%20it" \
  | jq '{count, best: .best.key}'
# {"count":12,"best":"NOW"}

curl -sS "https://miscsubjects.com/api/dispatch?key=TIME_NOW&format=markdown" \
  | sed -n '1,12p'
# begins: ## §SELF — miscsubjects capability (paste without context)

curl -sS -X POST "https://miscsubjects.com/api/dispatch" \
  -H "x-terminal-key: $TERMINAL_KEY" -H "content-type: application/json" \
  --data '{"key":"TIME_NOW","body":""}' | tee invocation.json \
  | jq '{ran, result, invocation_id: .invocation.id}'
# ran is true; result contains now, today, time, zone and iso

INVOCATION_ID="$(jq -r '.invocation.id' invocation.json)"
curl -sS "https://miscsubjects.com/api/dispatch?receipt=$INVOCATION_ID" \
  -H "x-terminal-key: $TERMINAL_KEY" | jq '{id, object_id, actor}'
# id equals $INVOCATION_ID and object_id identifies TIME_NOW
```

The live run at 05:06:05Z returned HTTP 200 for all four calls, resolved `NOW`, invoked `TIME_NOW` with `ran: true`, and read a 13,036-byte receipt. Tell the model these five endpoint shapes once, in a system prompt or skill file. Cost in tool definitions: zero.

**B. Small surface — one file, seven tools.** Prerequisite: an MCP SDK and somewhere to run it. On Cloudflare that is `McpAgent` from the `agents` package on a Durable Object, `McpServer` from `@modelcontextprotocol/sdk`, and `zod` for parameter schemas. Register `dispatch` with `{key, body}`, register one discovery tool that queries the table, expose `/mcp` for Streamable HTTP and `/sse` for the older transport, and gate both behind a bearer check. Working file: `workers/mcp-server/src/index.ts`.

The deployed server can be counted with the official TypeScript SDK:

```bash
npm install @modelcontextprotocol/sdk
export TERMINAL_KEY="<owner access key>"

node --input-type=module <<'JS'
import {Client} from "@modelcontextprotocol/sdk/client/index.js";
import {StreamableHTTPClientTransport} from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://miscsubjects.com/mcp"),
  {requestInit:{headers:{authorization:`Bearer ${process.env.TERMINAL_KEY}`}}}
);
const client = new Client({name:"count-tools",version:"1"},{capabilities:{}});
await client.connect(transport);
const listed = await client.listTools();
console.log(listed.tools.map(tool => tool.name));
await client.close();
JS
```

Expected output, measured at 05:04:50Z: `d1_query`, `kv_get`, `kv_put`, `list_directory`, `dispatch`, `oip_registry`, `oip_invocations` — seven definitions totalling 2,165 compact JSON bytes. The count stays seven when the catalogue doubles because only `dispatch` and the discovery calls refer to catalogue keys.

**C. Per-row MCP — the compatibility surface.** One SELECT, one loop, one normaliser. The normaliser is the part people skip and then get bitten by: coerce every schema to a root `type: "object"`, ensure every name in `required` exists in `properties`, give every property node a `type`, and flatten `anyOf`/`oneOf`/`allOf` to a representative branch — or a strict client rejects the entire list on the first bad row. Verify with:

```bash
curl -s -X POST https://<host>/api/mcp -H "Authorization: Bearer $MCP_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | python3 -c \
  "import json,sys;print(len(json.load(sys.stdin)['result']['tools']))"
```

Expected output: one integer, equal to the count of enabled, planner-visible rows.

## Symptom, cause, fix

| Symptom | Cause | Fix |
| --- | --- | --- |
| Client shows zero tools and no error | The whole `tools/list` was rejected on the first invalid schema; Moonshot and Kimi validate strictly | Normalise every schema: object root, every `required` name present in `properties`, a `type` on every node, no combinators. `functions/api/mcp.js:44–78` |
| `401 unauthorized` from `/api/mcp` | Bearer token mismatch | Send `Authorization: Bearer <MCP_TOKEN>` or the `x-mcp-token` header. The check is `functions/api/mcp.js:23–28` |
| Tens of thousands of input tokens before the first user message | The client loads every definition at connect | Turn on the client's deferred tool loading, or move to a small surface |
| A new capability is invisible to the client | The client ignores `notifications/tools/list_changed`, or the server declares `listChanged: false` | Reconnect the client. The three filed reports above show reconnect is the reliable path |
| A tool exists in the table but not in `tools/list` | The row has `enabled = 0` or `planner_visible = 0` | Intentional. `planner_visible = 0` keeps a capability callable by key while off the tool surfaces |
| 150 items means 150 tool calls | Round trips happen between completions | Expose an HTTP path a code sandbox can loop over, or one tool that takes a batch |
| Prompt cache hit rate collapses after adding a server | Definitions sit at the head of the context, and changing them invalidates the cache | Keep the definition set fixed across a session; load per-task capabilities through a call, not a definition |
| `codex exec` returns an empty turn | A configured server was deferred behind `tool_search` and never surfaced | `openai/codex#24536`. Pin the server as directly exposed until it closes |

The comparison against staying inside the schema paradigm entirely is [Tool Search and catalogue-as-data](/a/tool-search-vs-catalogue-as-data).

## Facts

```json
{
  "converted_from": "markdown",
  "original_updated": "2026-07-27T04:25:43.947Z",
  "register": "essay",
  "category": null
}
```

## Sources

1. [Model Context Protocol specification, revision 2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18) — “Model Context Protocol (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools.” (sha256 1eb1318c16447f9d)
2. [Tool search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/tool-search-tool) — “A typical multiserver setup (GitHub, Slack, Sentry, Grafana, and Splunk) can consume ~55k tokens in definitions before Claude does any work. Tool search typically reduces this by over 85 percent, loading only the 3-5 tools Claude needs for a given request.” (sha256 04db741bf04004dd)
3. [Code execution with MCP: building more efficient AI agents](https://www.anthropic.com/engineering/code-execution-with-mcp) — “This reduces the token usage from 150,000 tokens to 2,000 tokens—a time and cost saving of 98.7%.” (sha256 7169d57a1f36e4ab)
4. [Code Mode: the better way to use MCP](https://blog.cloudflare.com/code-mode/) — “With the traditional approach, the output of each tool call must feed into the LLM's neural network, just to be copied over to the inputs of the next call, wasting time, energy, and tokens. When the LLM can write code, it can skip all that, and only read back the final results it needs.” (sha256 cd1d0cd0e3b04ddb)
5. [McpAgent API — Cloudflare Agents](https://developers.cloudflare.com/agents/model-context-protocol/mcp-agent-api/) — “McpAgent” (sha256 7b97da949ac86783)
6. [Tools — MCP specification 2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18/server/tools) — “When the list of available tools changes, servers that declared the `listChanged` capability **SHOULD** send a notification” (sha256 6b72949ae2ecbb3a)
7. [Transports — MCP specification 2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports) — “MCP uses JSON-RPC to encode messages. JSON-RPC messages **MUST** be UTF-8 encoded.” (sha256 6c941ca9952ad3cf)
8. [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification) — “JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol.” (sha256 12f336762cbc5104)
9. [modelcontextprotocol/typescript-sdk](https://github.com/modelcontextprotocol/typescript-sdk/tree/v1.x) — “The Model Context Protocol allows applications to provide context for LLMs in a standardized way” (sha256 28e0be99236b658f)
10. [Kiro IDE does not handle MCP notifications/tools/list_changed — dynamic tools not refreshed](https://github.com/kirodotdev/Kiro/issues/6553) — “When an MCP server dynamically adds or removes tools at runtime and sends this notification per the MCP spec, Kiro IDE does not re-query tools/list, so the new tools never appear until the server is manually reconnected.” (sha256 66b8ff6fcc48b41a)
11. [GitHub Copilot CLI does not dynamically load tools via tools/list_changed](https://github.com/microsoft/wassette/issues/308) — “Internal terminal testing shows the CLI never refreshes its tool list, unlike GitHub Copilot in VS Code which updates immediately.” (sha256 eb5cde89e96f6db1)
12. [Dynamic tool sync: notifications/tools/list_changed + polling fallback](https://github.com/mcpjungle/MCPJungle/issues/260) — “MCPJungle caches upstream tool lists at registration time only. If an upstream server adds or removes tools later, MCPJungle's view stays stale until a manual re-registration or full restart.” (sha256 9ab3b999e3f99989)
13. [ToolSearch does not index tools from claude.ai-hosted MCP servers](https://github.com/anthropics/claude-code/issues/57033) — “the `ToolSearch` deferred-tool discovery mechanism does NOT include them in its index. Any `ToolSearch` query that should match a claude.ai MCP tool returns zero results” (sha256 eff1fce034d8afbf)
14. [codex exec can silently complete empty when configured MCP tools are deferred behind tool_search](https://github.com/openai/codex/issues/24536) — “`codex exec` can silently finish with no assistant message when an explicitly configured MCP tool is deferred behind `tool_search`.” (sha256 e1b5ba624c1129b4)
15. [Context bloat: 16.9k tokens wasted on MCP tool definitions loaded into main agent](https://github.com/yonatangross/orchestkit/issues/885) — “The main agent context burns **16.9k tokens (8.5% of 200k)** loading 68 MCP tool schemas at session start. Most are never called by the main agent — they're used by subagents.” (sha256 3e0cf2a987ca9fd3)
16. [Reduce Context Window Usage (13,341 tokens for tools alone)](https://github.com/abdlkrim-jribi/hcode/issues/4) — “The agent injects ALL 47 tool schemas on every single request, consuming ~13,341 tokens before the user message is even sent.” (sha256 89bf616341d33f51)
17. [Comment on: Apideck CLI — An AI-agent interface with much lower context consumption than MCP](https://news.ycombinator.com/item?id=47400262) — “We built a unified API with a large surface area and ran into a problem when building our MCP server: tool definitions alone burned 50,000+ tokens before the agent touched a single user message.” (sha256 c5dc7811fd6f0da1)
18. [Comment on: MCP is dead?](https://news.ycombinator.com/item?id=48336021) — “It's like saying APIs are dead because you can just use HTTP. They're not the same thing, though of course you can hand-roll the higher layer in the lower one. It's just more work, less standard, less valuable.” (sha256 2de7b95b80616ec0)
19. [Comment on: MCP is dead; long live MCP](https://news.ycombinator.com/item?id=47381322) — “MCP is effectively "just another HTTP REST API"; OAuth and everything.  The key parts of the protocol is the communication shape and sequence with the client, which most SDKs abstract for you” (sha256 19d6a50405652ac6)
20. [Comment on: MCP is dead; long live MCP — the contract is the value](https://news.ycombinator.com/item?id=47381282) — “Tool results from programmatic calls are not added to Claude's context window, only the final code output is. They report up to 98.7% token savings in some workflows.” (sha256 bd77883c8262ce25)
21. [Comment on: MCP is dead? — token cost is a harness detail](https://news.ycombinator.com/item?id=48331540) — “The idea that MCP tool definitions take up a certain number of tokens is laughable. That's an implementation detail of the agent harness.” (sha256 23037d070da563fb)
22. [Comment on: MCP is a fad — it is not a wire protocol](https://news.ycombinator.com/item?id=46553245) — “That is simply incorrect. It is not a wire protocol. Please do not mix terminology. MCPs communicate via JSON-RPC which is the wire protocol.” (sha256 31dc011ed94cdece)
23. [Comment on: What if you don't need MCP at all?](https://news.ycombinator.com/item?id=45955033) — “Right now loading GitHub MCP takes something like 50k tokens.” (sha256 5a53dcb41f603324)
24. [Comment on: Agent Skills — speed of light versus carrier pigeon](https://news.ycombinator.com/item?id=46878126) — “I call this "speed of light" as opposed to "carrier pigeon".” (sha256 5a5e389ee89b18b5)
25. [Comment on: Making MCP cheaper via CLI](https://news.ycombinator.com/item?id=47161005) — “With MCP the agent would have to do 150 tool calls and explode your context.” (sha256 727947b7b76e728b)
26. [Comment on: MCP is dead? — the arithmetic, and both sides](https://news.ycombinator.com/item?id=48330912) — “Say each tool is 150 tokens, that's 150 * 50, or 7500 tokens, dumped into the beginning of every session.” (sha256 07f7a9b2726eb8da)
27. [Comment on: MCP is dead? — every capability costs some context](https://news.ycombinator.com/item?id=48337283) — “This is a fundamental issue with anything that just adds a bunch of tools, whether it be via MCP or HTTP (still sad that MCP won over OpenAI's HTTP based approach).” (sha256 a4805f8d0bdc5fdc)
28. [Comment on: When does MCP make sense vs CLI?](https://news.ycombinator.com/item?id=47212763) — “MCP is just "me too"; people want MCP to be an "AI App Store"; but the blunt, harsh reality is that it's basically impossible to achieve that dream” (sha256 92070df59b558135)
29. [Comment on: Show HN: Epiq — skills versus MCP](https://news.ycombinator.com/item?id=48158034) — “Skills effectively turned MCPs obsolete in the vast majority of MCP applications.” (sha256 4574d503f3afc45b)
30. [Comment on: Running Gemma 4 locally with LM Studio's headless CLI and Claude Code](https://news.ycombinator.com/item?id=47659574) — “With a handful of third party MCPs I've seen tens of thousands of tokens used before I've started anything.” (sha256 ce1dab032ba16749)
31. [Comment on: Chrome DevTools MCP — tool search does not fully solve it](https://news.ycombinator.com/item?id=47392361) — “And no, the tool search function recently introduced by Anthropic does not completely solve this problem.” (sha256 686b8b569e20ca67)
32. [Comment on: When does MCP make sense vs CLI? — dynamic tools bust the cache](https://news.ycombinator.com/item?id=47209810) — “The main problem with this approach at the moment is it busts your prompt cache, because LLMs expect all tool definitions to be defined at the beginning of the context window.” (sha256 52099c72c3c160d3)
33. [Comment on: Show HN: Ismcpdead.com — definitions that never fire](https://news.ycombinator.com/item?id=47646880) — “It's annoying to see the context window shrink just from tool definitions that never even get triggered.” (sha256 74675b6800d8c515)
34. [First-party measurement: tools/list against the per-row MCP surface, 2026-07-26](https://miscsubjects.com/api/articles/mcp-as-a-projection) — “http=200 bytes=434636 time=0.267195s — tool_count 831, compact definitions_bytes 434592, average_definition_bytes 523” (sha256 6800fc29167ce6df)
35. [First-party measurement: the protocol surface reaches every capability with zero tool definitions, 2026-07-26](https://miscsubjects.com/api/dispatch?registry=1) — “http=200 bytes=1606794 time=0.397555s — 876 objects” (sha256 3d6897f8acf0adae)
36. [First-party receipt: initialize and tools/call against the live server, 2026-07-26](https://miscsubjects.com/api/articles/mcp-as-a-projection) — “{"jsonrpc":"2.0","id":0,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{"listChanged":false}},"serverInfo":{"name":"miscsubjects-directory","version":"1.0.0"}}}” (sha256 aac2f1f49ffb2d23)
37. [The source files behind the three surfaces, and the seven-versus-six correction](https://miscsubjects.com/api/articles/mcp-as-a-projection) — “grep -c 'this.server.tool(' workers/mcp-server/src/index.ts → 7” (sha256 19605291fa335e84)
38. [First-party measurement: tools/list against the seven-tool MCP surface, 2026-07-26](https://miscsubjects.com/) — “tool_count 7 — d1_query, kv_get, kv_put, list_directory, dispatch, oip_registry, oip_invocations — definitions_bytes 2165” (sha256 800cac0cf0f32e2d)