# Cutting MCP tool overhead with a catalog and Code Mode

> Eleven attached MCP servers cost about 28k tokens before any work. How Nested hides connectors behind a catalog and lets agents script tool calls.

Published: 2026-10-22 · Updated: 2026-11-19 · Topics: Agents, Architecture · Canonical: https://nested.me/blog/mcp-catalog-and-code-mode

## The tax nobody budgets for

Every MCP server attached to a model session ships its tool schemas into the context window. One server is fine. But a real agent has GitHub, Slack, Jira, Sentry, a few Google Workspace tools, its pack’s servers, and the platform’s own tools. When we measured live sessions with 11 attached servers, the floor was about 28,000 tokens of tool schemas before the user typed anything.

That cost is paid on every turn, by every agent, whether or not it touches those tools. And it buys worse behavior, not better: a model choosing between two hundred tools picks wrong more often than one choosing between twenty.

## Where an agent’s tools come from

An agent in Nested has three sources of tools:

1. **The built-in `nested` server.** It is part of the agent binary and exposes the platform: discovering and messaging other agents, knowledge and memories, formulas, files and object storage, asking the user for input, site logins, and the connector catalog.
2. **Connectors.** Remote MCP servers that a person connects once with OAuth or a credential — GitHub, Slack, Atlassian, Sentry, Gmail, Drive, Docs, Sheets, Slides, and a zero-trust gateway connector. Team owners can add custom ones.
3. **Pack MCP servers.** Servers a pack declares, installed at agent startup from npm, a command, a remote URL, or a downloaded binary whose SHA-256 is checked.

## The catalog: attach little, discover everything

With session catalog mode, which is on by default, the agent does not attach every server to the session. It attaches an “eager” set — always including `nested` — and hides the rest behind four tools:

| Tool | What it does |
| --- | --- |
| `nested_mcp_list` | Lists available servers with a one-line “when to use” hint. No schemas, no secrets. |
| `nested_mcp_describe` | Fetches one server’s tools, as JSON Schema or as compact TypeScript signatures. |
| `nested_mcp_call` | Calls one tool on one server. |
| `nested_mcp_exec` | Runs a short script that can call many tools and return one result (Code Mode). |

The model still knows what exists — the list is short and cheap — but it only pays for a schema when it decides to use that server. Describes are cached for the life of the process, and concurrent describes of the same server share one request.

The TypeScript format matters more than it sounds. JSON Schema is verbose; a TypeScript signature carries the same information in far fewer tokens. Our estimate when we designed it was 50–70% fewer tokens per describe.

## Code Mode: do the loop where the data is

The catalog fixes the fixed cost. It does not fix multi-hop work. “Find every open Sentry issue for this service, look up the commit that introduced each one, and tell me which teams own them” is a dozen calls, and every intermediate payload lands in the context and gets billed again on each later turn.

`nested_mcp_exec` lets the agent write that loop as JavaScript and get back only the answer:

```js
// Tool names and arguments are illustrative; describe a connector to see its real tools.
const issues = mcp.call("sentry", "list_issues", { project: "api", status: "unresolved" });
const commits = mcp.callAll(
  issues.slice(0, 10).map((i) => ({ name: "github", tool: "get_commit", args: { sha: i.sha } })),
);
return commits.filter((r) => r.ok).map((r) => r.value.author);
```

The script runs in a fresh, in-process JavaScript VM (goja, written in pure Go). Its only capabilities are the `mcp` object and `console` logging. There is no filesystem, no network, no `require`, and no timers. A watchdog samples memory every 25 ms and stops the script on timeout or excessive heap growth.

| Limit | Default |
| --- | --- |
| Script timeout | 60 s (max 120 s) |
| Upstream calls per script | 25 |
| Parallel calls in `callAll` | 4 (max 8) |
| Result size | 64 KiB |
| Concurrent scripts per session | 4 |

The result includes an audit trail of every upstream call — connector, tool, duration, error — so you can see in the runbook exactly what the script did.

## What happens when a task starts

The catalog is rebuilt for every task, because every task can belong to a different person:

1. At startup, the agent installs the MCP servers its packs declare and prepends the built-in `nested` server. If a pack server has the same name, the built-in one wins.
2. When a task starts, the agent asks the control plane for the connectors of the task’s owner in the task’s team, skipping any that need reconnection.
3. It rewrites each connector’s URL to point at the loopback token proxy and binds a fresh per-task token generation.
4. It splits everything into the eager set, which is attached to the session, and the catalog, which is handed only to the `nested` server.
5. It fills per-session placeholders such as the workspace path and the task and context ids.

If the `nested` server is missing for some reason, the agent fails open and attaches everything, so a broken catalog costs tokens instead of tools.

## Keeping tokens away from the model

A catalog full of connectors is a catalog full of credentials. We made three choices so the model and the workspace never see them:

- The connector list reaches the `nested` process only through its own environment, and the list tool returns a secret-free view.
- Live OAuth tokens are injected by a loopback reverse proxy inside the agent pod. Coding-agent sessions call the proxy; the proxy adds the bearer token and refreshes it when it is within 60 seconds of expiring.
- If an upstream returns 401 or 403, the proxy refreshes and retries once. A 403 that survives a fresh token marks the connector as needing reconnection, which shows up in the app so a person can reconnect.

A task only sees the connectors of the account that owns it, in that task’s team. When the agent delegates to another agent, the child task inherits the same owner — delegation never widens access.

## No central proxy, on purpose

Tool traffic goes straight from the agent pod to the upstream server. The connector service in the control plane handles the catalog, OAuth, encrypted token storage, and resolution — but it does not sit in the middle of every call. A central proxy would be one more hop, one more thing to scale, and one more place where every team’s traffic meets.

## Team connectors and SSRF

Team owners and admins can add a custom remote MCP server for their team, with per-member OAuth or shared headers. Because those URLs come from users, they go through an SSRF guard: HTTPS only, no credentials in the URL, and every resolved address must be public unicast. The address is re-checked at dial time, which defeats DNS rebinding. Shared header names are allow-listed, and names like `host` and `cookie` are always refused.

## Trade-offs

- **One more step for the model.** List, describe, then call is slower than calling an attached tool. For servers an agent uses on almost every turn, mark them eager.
- **Scripts are JavaScript.** It is the language models write most reliably for this kind of glue. It is not a general runtime, and it is not meant to be.
- **The old registry is gone.** An earlier design pulled servers from public MCP registries into a searchable catalog. We retired it: servers now come from packs (reviewed with everything else an agent loads) and connectors (connected by a person).

## Closing

The best tool call is the one whose schema you never loaded. If you want your agents to reach a new system, connect it once on the [Connectors](https://nested.me/docs/connectors) page, or ship it in a [pack](https://nested.me/docs/packs).

## Questions

### What is MCP Code Mode in Nested?

A built-in tool, `nested_mcp_exec`, that runs a short JavaScript script in a sandboxed VM. The script can call many MCP tools and returns only its final result, which saves tokens on multi-step work.

### Why not attach every MCP server to the agent session?

Tool schemas cost context on every turn. Sessions with 11 attached servers started at about 28k tokens. The catalog lets the agent load a schema only when it needs it.

### Can the model see my connector OAuth tokens?

No. A loopback proxy in the agent pod injects and refreshes tokens, and the catalog tools return a view without credentials.
