One Query Parameter Cut 19% of Our Claude Code Context Burn

The problem¶

When an MCP client opens a session, the server responds to tools/list with every tool the server exposes. For gotcontext, that list grew to 142 entries. At the token level, serializing 142 tool names, descriptions, and parameter schemas costs roughly 38,000 tokens.

At Anthropic's published Sonnet 4.6 pricing of $3.00 per million input tokens, that tools/list response costs ~$0.114 per cold session start, before a single compression call happens (source: Anthropic pricing + CHANGELOG v1.23.18).

38K tokens is 19% of a 200K context window and 30% of a 128K context window. For any agent running a session with a bounded context limit, that share is unavoidable without a way to request a smaller tool surface. We did not have that way until v1.23.18.

The problem is catalogued in CLAUDE.md, written from our own dogfood loop (we use gotcontext on this codebase): “142-tool surface burns 19-30% of major-model context.”

What shipped in v1.23.18¶

The CHANGELOG v1.23.18 entry (2026-05-18) describes the change:

New ?profile=core returns a small set of essential tools (~2K tokens vs ~38K). Thinktank verdict (codex + gemini, 5-of-6 voices): default to full, opt-in to core.

Three deliverables landed in one commit:

1. The query param. /mcp?profile=core and /mcp?profile=full both work. Any unknown value falls through to full.
2. The plugin bundle default. plugins/gotcontext/mcp-servers/gotcontext.json now ships with ?profile=core in the URL. Existing gc_ keys already in production continue pointing at the unparameterized URL and receive the full tool list.
3. Three E2E regression tests verify that core returns the smaller tool set, full returns 142, and unknown values fall back to full.

The gateway architecture handles the dispatch behind the public endpoint. From a client perspective the only change is the query parameter on the MCP URL.

What the core profile includes¶

Core covers the complete ingest-read-search-expand-manage lifecycle. An agent using core can add a document, get its compressed skeleton, search within it, expand any region, check stats, list documents, and delete documents it no longer needs. That set of capabilities serves the majority of agentic context-engineering workflows without the full 142-tool catalog overhead.

Calls to tools outside the core profile return a tool-not-found response. Agents that need a wider surface ask for the full profile explicitly via the query parameter on the MCP URL.

Auth and back-compat¶

Auth runs before the profile dispatch, so both profiles share the same bearer-token authentication layer. No separate key is needed for core vs full. Existing gc_ keys already in production continue to point at the unparameterized URL and receive the full tool list, preserving back-compat for every dogfood and customer key in circulation at the time of the v1.23.18 ship.

Cold dispatch overhead on every MCP request is a query-string parse and a branch. No measurable latency cost at the gateway.

What 19% means (and does not mean)¶

The 19% figure is a context-window share, not a session cost reduction. Definitions:

The cost reduction is at session initialization only. Per-call costs (input + output for each compression or search call) are identical between profiles. If your workflow uses 30 tool calls per session at an average of 500 input tokens each, the tools/list saving is 38K / (38K + 15K) = 72% of the session's total input at session start, but a smaller fraction of the session's total token spend.

The manifest reduction is 38K to 2K = 95%. The 19% figure refers to what the full profile occupied in a 200K window, not how much total cost drops. Both numbers are real; they measure different things.

Backward compatibility¶

The server default is unchanged: /mcp (no query param) continues returning all 142 tools. At the time of ship, more than 100 gc_ keys were in circulation pointing at the unparameterized URL. Changing the server default would have broken all of them. The CHANGELOG note reads:

The unparameterized URL continues advertising all 142 tools. Existing installs continue working unchanged.

The break was taken at the plugin bundle layer instead. New installs that follow the setup guide get ?profile=core by default because plugins/gotcontext/mcp-servers/gotcontext.json now ships with the param in the URL. Existing users who want core need to update their config once; the how-to is in the final section.

The thinktank decision¶

Before shipping, we ran the design question through a multi-model review: should the server default be core or full? The CHANGELOG records the result:

Thinktank verdict (codex + gemini, 5-of-6 voices): default to full, opt-in to core.

The reasoning: changing the server default had no upside for users who had already integrated with the full surface. The 38K-token cost is real but not an emergency for existing users who had decided the full catalog was worth the context spend. Newcomers, who have not built expectations around specific tool names, benefit from starting with a smaller surface.

The 5-of-6 vote left one model favoring an immediate server-default flip. That dissenting voice's concern was that 19% context waste is material enough to justify a one-time migration cost for existing users. We recorded the dissent and stayed with the consensus: full server default, core plugin default.

Honest disclosure¶

How to switch profiles¶

If you installed the plugin before v1.23.18 and want to opt into core, update the URL in your MCP config:

{
  "mcpServers": {
    "gotcontext": {
      "type": "http",
      "url": "https://api.gotcontext.ai/mcp?profile=core",
      "headers": {
        "Authorization": "Bearer ${GOTCONTEXT_API_KEY}"
      }
    }
  }
}

To stay on the full 142-tool surface, remove the query param or use ?profile=full:

{
  "mcpServers": {
    "gotcontext": {
      "type": "http",
      "url": "https://api.gotcontext.ai/mcp?profile=full",
      "headers": {
        "Authorization": "Bearer ${GOTCONTEXT_API_KEY}"
      }
    }
  }
}

The core_stable alias (visible in the router source at line 3380) is treated identically to core. It exists so future changes to the core set can be versioned without breaking clients that pin by name.