Practical notes: The hidden cost of ‘just add an .mcp.json
Operable walkthrough of Practical notes: The hidden cost of ‘just add an .mcp.json’: contracts, checks, and drop-in code slots for teams shipping this pattern.
This article is published in English.
The following notes reconstruct a practical path around “The hidden cost of ‘just add an .mcp.json’”. Emphasis stays on contracts, checks, and drop-in code placeholders rather than motivational framing. When working through the Overview stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments.
How tool schemas enter your context
The How tool schemas enter stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Expose tools with narrow schemas and explicit side-effect labels. Hosts need to know which calls mutate state before they auto-approve.
{
"name": "slack_send_message",
"description": "Send a message to a Slack channel or user",
"inputSchema": {
"type": "object",
"properties": {
"channel": {
"type": "string",
"description": "Channel ID or name to send the message to"
},
"text": {
"type": "string",
"description": "The message content to send"
},
"thread_ts": {
"type": "string",
"description": "Optional thread timestamp to reply in a thread"
}
},
"required": ["channel", "text"]
}
}
The baseline tax you can’t avoid
The The baseline tax you stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Expose tools with narrow schemas and explicit side-effect labels. Hosts need to know which calls mutate state before they auto-approve.
The real numbers: a typical .mcp.json
The The real numbers a stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Expose tools with narrow schemas and explicit side-effect labels. Hosts need to know which calls mutate state before they auto-approve. The The real numbers a stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments.
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"]
},
"slack": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-slack"]
},
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/projects"]
},
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"]
},
"memory": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory"]
}
}
}
Why this hurts more than the dollar cost suggests
For the Why this hurts more stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Authenticate at the gateway and re-authorize at the data plane. A bearer token alone is not a tenancy boundary.
1. Tool schemas compete with your conversation for the same fixed window.
For the 1 Tool schemas compete stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Authenticate at the gateway and re-authorize at the data plane. A bearer token alone is not a tenancy boundary.
2. More tools increases latency and selection errors.
For the 2 More tools increases stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Authenticate at the gateway and re-authorize at the data plane. A bearer token alone is not a tenancy boundary. For the 2 More tools increases stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments.
3. Server startup adds latency beyond the token cost.
When working through the 3 Server startup adds stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Cache stable system instructions and tool schemas. Re-sending identical preamble is a common source of burn.
How Claude Code already mitigates this
When working through the How Claude Code already stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Log tool name, args hash, latency, and outcome for every call. Debugging agent loops without that trail wastes hours.
The following deferred tools are now available via ToolSearch.
Their schemas are NOT loaded - calling them directly will fail
with InputValidationError. Use ToolSearch with query
"select:<name>[,<name>...]" to load tool schemas before calling them:
mcp__plugin_slack_slack__slack_send_message
mcp__plugin_slack_slack__slack_read_channel
mcp__plugin_github_github__list_recent_viewer_prs
...
What you can do about it
When working through the What you can do stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Log tool name, args hash, latency, and outcome for every call. Debugging agent loops without that trail wastes hours.
1. Audit your tool schema cost
When working through the 1 Audit your tool stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Log tool name, args hash, latency, and outcome for every call. Debugging agent loops without that trail wastes hours.
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
const transport = new StdioClientTransport({
command: "npx",
args: ["-y", "@modelcontextprotocol/server-github"],
env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN! }
});
const client = new Client({ name: "audit", version: "1.0.0" });
await client.connect(transport);
const { tools } = await client.listTools();
console.log(`Server exposes ${tools.length} tools`);
let totalTokens = 0;
for (const tool of tools) {
const schemaStr = JSON.stringify(tool);
// ~3-4 chars per token for JSON; this is a rough lower bound
const estimatedTokens = Math.ceil(schemaStr.length / 3.5);
totalTokens += estimatedTokens;
console.log(` ${tool.name}: ~${estimatedTokens} tokens`);
}
console.log(`\nEstimated context cost: ~${totalTokens} tokens/turn`);
console.log(`(For exact counts, use Anthropic's token counting API)`);
await client.close();
2. Use project-scoped configs
When working through the 2 Use project-scoped configs stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Log tool name, args hash, latency, and outcome for every call. Debugging agent loops without that trail wastes hours.
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"]
}
}
}
3. Prefer servers that expose fewer, well-scoped tools
When working through the 3 Prefer servers that stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Log tool name, args hash, latency, and outcome for every call. Debugging agent loops without that trail wastes hours.
4. Implement deferred loading if you’re building a client
When working through the 4 Implement deferred loading stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Log tool name, args hash, latency, and outcome for every call. Debugging agent loops without that trail wastes hours.
// What goes into the system prompt (cheap, ~5-8 tokens per tool):
const toolDirectory = tools.map(t => t.name);
const systemPrompt = `Available tools (use ToolSearch to load): ${toolDirectory.join(", ")}`;
// What goes into the API request's tools parameter (expensive):
// Only include tools the model has explicitly requested via ToolSearch
const activeTools: ToolSchema[] = [];
// When the model calls ToolSearch("slack_send_message"):
function loadTool(name: string) {
const schema = cachedSchemas.get(name);
if (schema) activeTools.push(schema);
}
// API call only pays for activeTools, not all 200
const response = await anthropic.messages.create({
tools: activeTools, // 1-4 tools, not 200
system: systemPrompt,
messages: conversation,
});
The verdict
When working through the The verdict stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Log tool name, args hash, latency, and outcome for every call. Debugging agent loops without that trail wastes hours. When working through the The verdict stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments.
Operational checklist
For the Operational checklist stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state.
Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion.
Authenticate at the gateway and re-authorize at the data plane. A bearer token alone is not a tenancy boundary.
Write a short runbook: how to rotate keys, how to drain the queue, how to roll back the last ingest.
Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments.
Authenticate at the gateway and re-authorize at the data plane. A bearer token alone is not a tenancy boundary.
Before promoting the stack, freeze versions, capture a golden transcript for the critical path, and confirm rollback steps. Shared environments need rate limits, tenancy checks, and a clear owner for secret rotation. Prefer boring reliability over clever one-off demos.
Batch note for 06d5cd938e01: keep provider keys out of the repo, set a per-session token ceiling, and store transcripts next to the eval fixtures so later model swaps stay comparable.