Reducir el consumo de tokens de MCP: cómo recortamos un 60 % nuestras definiciones de herramientas

El 27 de octubre, un usuario de pago canceló su suscripción a AgentsRoom y dio los tokens como motivo. Antes de discutirlo, medimos lo que nuestra app añade a cada agente que lanza.

La cifra más grande no estaba donde esperábamos. Nuestras instrucciones de arranque eran pequeñas. Las herramientas MCP que damos a cada agente (backlog, memoria del proyecto, correo entre agentes, terminales, SSH, bases de datos y el resto) eran 191 herramientas y unos 380 KB de JSON. A unos 4 bytes por token, eso son unos 95.000 tokens de definiciones de herramientas. Una semana antes eran 78.000. Nadie lo había decidido: cada herramienta nueva simplemente había añadido su párrafo.

Desarrollamos AgentsRoom, una app de escritorio que ejecuta Claude Code, Codex y otros CLI de código en paralelo y les da estas herramientas. Esto es lo que medimos, lo que recortamos sin quitar una sola herramienta y el control que impide que vuelva. Puedes aplicar todo esto a tus propios servidores MCP.

La respuesta corta

• Una definición de herramienta es JSON que el modelo puede leer en cada solicitud: nombre, descripción, esquema de entrada. Cuenta unos 4 bytes por token.
• Que lo pagues en cada turno o no depende del CLI. Claude Code difiere las herramientas MCP por defecto y carga una definición cuando la necesita. Algunos CLI envían todos los esquemas con cada solicitud.
• Mide antes de recortar. /context en Claude Code, o un script de 40 líneas que pide su lista de herramientas a cualquier servidor.
• Acorta el texto, conserva las herramientas. Una descripción dice qué y cuándo. El manual pasa a un documento que el agente lee cuando lo necesita. Las nuestras pasaron de unos 95.000 a unos 38.000 tokens, 2,5 veces menos.
• Pon un tope en el build. Sin él, las definiciones vuelven a crecer solas.

Lo que cuesta una definición de herramienta, y quién lo paga

Cuando un cliente MCP se conecta a un servidor, le pide la lista de herramientas. Cada entrada es un nombre, una descripción escrita para el modelo y un esquema JSON de los parámetros. El cliente convierte esa lista en definiciones de herramientas enviadas al modelo: así sabe el modelo que la herramienta existe y cómo llamarla.

Así que cada palabra de una descripción es entrada que el modelo lee. Con qué frecuencia la lee depende del cliente:

• Claude Code difiere las herramientas MCP por defecto. Su documentación, leída el 3 de noviembre de 2026 con Claude Code 2.1.314 instalado, dice que al iniciar la sesión solo se cargan los nombres de las herramientas y las instrucciones de los servidores, y que una definición se carga mediante la búsqueda de herramientas cuando Claude necesita esa herramienta. Con ENABLE_TOOL_SEARCH=false, con auto por debajo de un umbral del 10 % de la ventana de contexto, en modelos anteriores a Claude Opus 4 y Sonnet 4, o para un servidor marcado como alwaysLoad, las definiciones se cargan desde el principio.
• Otros CLI lo hacen distinto. En nuestra propia prueba del 28 de octubre, con un agente al que se pedía responder «OK»: Claude Code arrancaba en 67.500 tokens con nuestras herramientas diferidas, Codex CLI 0.164 arrancaba en 25.000 tokens y no enviaba nuestros esquemas en un solo bloque, y OpenCode cargaba nuestras 175 herramientas más 19 herramientas de navegador al conectarse y las enviaba con cada solicitud. Mismo servidor, facturas muy distintas.

La caché de prompt suaviza el coste cuando la lista de herramientas no cambia: tras la primera solicitud, un prefijo estable se lee desde la caché a una fracción del precio de entrada. No devuelve el espacio. Las definiciones siguen ocupando la ventana de contexto en cada solicitud, junto a tu código y tu conversación. Y el modo diferido tiene su propio coste: un paso de búsqueda antes del primer uso de cada herramienta.

Mide las tuyas en dos minutos

En Claude Code, ejecuta /context. Desglosa la ventana por origen y marca las herramientas MCP diferidas o cargadas bajo demanda. Ejecútalo en una sesión nueva de tu proyecto, antes de escribir nada, y verás lo que cuesta tu configuración antes de que empiece el trabajo.

Para cualquier servidor y cualquier CLI, pregunta directamente al servidor. Un servidor MCP por stdio habla JSON-RPC, un mensaje por línea: envías initialize, luego tools/list, y mides lo que vuelve. Este script hace exactamente eso, con Node y sin ninguna dependencia:

// Usage: node mcp-tool-cost.mjs <command that starts the server> [args...]
import { spawn } from 'node:child_process';

const [cmd, ...args] = process.argv.slice(2);
const server = spawn(cmd, args, { stdio: ['pipe', 'pipe', 'ignore'], shell: process.platform === 'win32' });
const tools = [];
let buffer = '';

const send = (msg) => server.stdin.write(JSON.stringify({ jsonrpc: '2.0', ...msg }) + '\n');
const listTools = (cursor) => send({ id: 2, method: 'tools/list', params: cursor ? { cursor } : {} });

server.stdout.on('data', (chunk) => {
  buffer += chunk;
  let end;
  while ((end = buffer.indexOf('\n')) >= 0) {
    const line = buffer.slice(0, end).trim();
    buffer = buffer.slice(end + 1);
    if (line) handle(JSON.parse(line));
  }
});

function handle(msg) {
  if (msg.id === 1) {
    send({ method: 'notifications/initialized' });
    listTools();
  } else if (msg.id === 2) {
    tools.push(...msg.result.tools);
    if (msg.result.nextCursor) listTools(msg.result.nextCursor);
    else { report(); server.kill(); }
  }
}

function report() {
  const rows = tools
    .map((tool) => ({ name: tool.name, bytes: Buffer.byteLength(JSON.stringify(tool)) }))
    .sort((a, b) => b.bytes - a.bytes);
  const total = rows.reduce((sum, row) => sum + row.bytes, 0);
  for (const row of rows.slice(0, 10)) {
    console.log(`${String(row.bytes).padStart(7)} bytes  ~${Math.round(row.bytes / 4)} tokens  ${row.name}`);
  }
  console.log(`${rows.length} tools, ${total} bytes, about ${Math.round(total / 4)} tokens`);
}

send({
  id: 1,
  method: 'initialize',
  params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'tool-cost', version: '1.0.0' } },
});

Ejecútalo con el mismo comando que usa tu CLI para arrancar el servidor, por ejemplo node mcp-tool-cost.mjs npx -y @playwright/mcp@latest. Muestra las diez herramientas más pesadas y el total. Esto es lo que obtuvimos el 3 de noviembre de 2026:

Cuatro bytes por token es una estimación, suficiente para comparar servidores y ver una tendencia, no para predecir una factura. Los tokenizadores reales varían según el modelo y el texto, como vimos al contar 3.800 millones de nuestros propios tokens.

Los servidores de archivos de arriba son razonables. El problema es la suma: cinco servidores de ese tamaño ya son 20.000 tokens, antes de un servidor como el nuestro.

Lo que recortamos, y lo que no tocamos

La regla que nos pusimos: ninguna herramienta quitada, ningún parámetro quitado, ningún valor permitido ni campo obligatorio quitado. Los agentes tenían que conservar todas sus capacidades. Solo podía cambiar el texto.

1. Una descripción de herramienta dice qué y cuándo, en una a tres frases. No cómo. El cómo era donde estaban los bytes: reglas, valores por defecto, casos límite, ejemplos, advertencias escritas después de que un agente usara mal la herramienta una vez.
2. Un parámetro recibe una frase, o nada cuando su nombre, su tipo y su lista de valores permitidos ya lo dicen todo. Los parámetros que se repiten entre herramientas (project, author, ids de ticket) recibieron la misma frase estándar en todas partes.
3. El manual se mudó, no se borró. Cada familia de herramientas tiene un archivo de instrucciones que el agente lee antes de su primera llamada a esa familia. Para nuestra herramienta más grande, la que guarda un equipo de agentes, la referencia completa de campos la devuelve ahora una llamada a una herramienta cuando el agente la pide, en lugar de viajar dentro del esquema.
4. Una segunda pasada comprobó cada dato. Cada frase quitada de una descripción se buscó en los archivos de instrucciones, y se añadió allí cuando faltaba.

Algunos de los resultados, en bytes de JSON por herramienta:

En total, 380 KB pasaron a 152 KB. Trece herramientas superaban los 4 KB; cuatro todavía los superan, por la cantidad de campos que llevan. La idea detrás de toda la pasada: para elegir una herramienta, el modelo necesita saber que existe y cuándo llamarla. Los detalles pueden esperar al momento en que la usa.

Si escribes un servidor MCP, Claude Code te da una razón más. Corta a 4.096 caracteres una descripción de herramienta cargada desde el principio, y cuando compara una búsqueda con una descripción solo lee la parte dentro de ese límite. Lo importante que venga después puede no leerse nunca.

El mismo truco para un archivo de arranque

Los esquemas de herramientas no son el único coste fijo. Nuestros agentes también leen un archivo de instrucciones sobre las herramientas antes de usarlas, y había crecido hasta 57,7 KB, unos 14.000 tokens, leídos enteros en cada arranque y en cada reanudación. Un usuario nos informó de que un agente de Codex reanudado alcanzaba su límite de contexto de trabajo en pocos minutos.

La corrección siguió la misma idea. El archivo pasó a ser un índice de unos 11 KB: las reglas que valen para todas las herramientas, y una línea por familia de herramientas que apunta a su propio archivo. Los 31 archivos de familia solo se leen antes de la primera llamada a esa familia. Su texto no cambió, palabra por palabra. Un agente que solo toca el backlog nunca lee la sección sobre bases de datos.

Esto también funciona para cualquier CLAUDE.md o AGENTS.md largo: deja en el archivo que siempre se carga lo que necesita cada tarea, y enlaza el resto. Hablamos más de ello en nuestra guía sobre AGENTS.md y los archivos de contexto.

Un presupuesto que hace fallar el push

La cifra que más nos preocupaba no era 95.000. Era 78.000 una semana antes. Cada herramienta añadía un párrafo, cada párrafo era razonable, y la suma creció un 20 % en siete días.

Así que el tamaño pasó a ser un control del build. Un archivo JSON guarda el presupuesto:

{
  "totalBytes": 160000,
  "perToolBytes": 4000,
  "oversized": {
    "teams_save": 9791,
    "triggers_save": 4071,
    "backlog_update": 4253,
    "backlog_create": 4399
  }
}

Un script arranca nuestros servidores MCP en un sandbox, pide a cada uno sus herramientas, mide JSON.stringify(tool) en bytes y sale con error cuando el total supera totalBytes o cuando una herramienta supera perToolBytes. Las cuatro herramientas que ya eran demasiado grandes están listadas con su tamaño: un trinquete. Pueden adelgazar, nunca crecer, y cuando una adelgaza, el script pide bajar la cifra. Se ejecuta antes de cada push y en el build de release. Subir el tope es posible, pero es una decisión escrita en el archivo, no una forma de hacer pasar el control.

El 3 de noviembre, seis días después, el mismo control marca 203 herramientas y 159.957 bytes: doce herramientas añadidas, 43 bytes por debajo del tope. La próxima herramienta tendrá que hacerse sitio ella misma. Para eso sirve exactamente el control.

Desactiva lo que no usas

El token más barato es el de la herramienta que tu agente nunca ve.

• Limita los servidores a los proyectos que los necesitan. Un servidor declarado a nivel de usuario te sigue a cada repositorio. En Claude Code, un .mcp.json de proyecto lo deja donde es útil.
• Reserva alwaysLoad para un puñado de herramientas. La documentación de Claude Code lo dice claramente: cada herramienta cargada desde el principio consume contexto que de otro modo estaría disponible para tu conversación.
• Vigila lo que añaden los resultados de las herramientas, no solo las definiciones. Una herramienta que devuelve una página o una tabla entera puede costar más en una llamada que su definición en todo un día.

En AgentsRoom, Ajustes > Herramientas de AgentsRoom lista cada familia de nuestras herramientas con su peso, y puedes desactivar una familia o una sola herramienta, para todos los proyectos, un proyecto, una carpeta o un solo agente. Una herramienta desactivada ni siquiera se presenta al agente, así que no cuesta contexto. La página AgentsRoom MCP describe las herramientas, y la traza de la sesión muestra lo que llenó el contexto de un agente, herramientas MCP incluidas, ordenado por tamaño.

Lo que no cambiamos

De la misma medición salieron otros dos costes, y los dejamos como estaban a propósito.

• El brief de arranque que dice a cada agente su rol y cómo informar de su estado: una mediana de unos 5.000 tokens para Claude, alrededor del 2,5 % de una ventana de 200.000 tokens, y leído desde la caché a partir de la segunda solicitud.
• El archivo de estado que cada agente escribe al final de un turno: medido en 71 transcripciones locales de Claude, alrededor del 2,5 % de los tokens de contexto.

Reducir cualquiera de los dos habría ahorrado menos del 3 % de la ventana y puesto en riesgo la calidad del trabajo de los agentes. Las definiciones de herramientas eran 95.000 tokens. Ahí fue donde dedicamos el tiempo.

Preguntas que la gente hace de verdad

¿Cuántos tokens consumen las herramientas MCP?

Cada herramienta cuesta su definición entera: nombre, descripción y esquema de entrada, enviados como JSON. Una regla aproximada es 4 bytes por token. Medido el 3 de noviembre de 2026: el servidor filesystem oficial lista 14 herramientas por unos 3.100 tokens, Playwright MCP 25 herramientas por unos 5.300. Las herramientas de AgentsRoom pesaban unos 95.000 tokens antes de que las acortáramos, unos 40.000 hoy.

¿Claude Code carga todas las herramientas MCP en la ventana de contexto?

No por defecto. La búsqueda de herramientas de Claude Code (tool search) difiere las definiciones de las herramientas MCP: al iniciar la sesión solo se cargan los nombres de las herramientas y las instrucciones de los servidores, y Claude carga una definición cuando necesita esa herramienta. ENABLE_TOOL_SEARCH=false, un modelo anterior a Claude Opus 4 y Sonnet 4, o un servidor marcado como alwaysLoad vuelven a poner las definiciones en el contexto desde el principio.

¿Los servidores MCP reducen el consumo de tokens?

Pueden hacerlo, cuando una herramienta devuelve una respuesta corta en lugar de algo que el agente leería entero, como una consulta a una base de datos en lugar de un volcado completo. Pero las definiciones cuestan contexto, y los resultados también: Claude Code avisa cuando un resultado MCP supera los 10.000 tokens y lo corta a los 25.000 por defecto. Un servidor MCP solo ahorra tokens cuando sus resultados son más pequeños que lo que sustituye.

¿Cómo veo cuánto contexto ocupan mis herramientas MCP?

En Claude Code, ejecuta /context: desglosa el contexto por origen y marca las herramientas MCP diferidas. Para cualquier servidor y cualquier CLI, pide al servidor su lista de herramientas y mide el JSON, que es lo que hace el script de 40 líneas de este artículo.

¿Qué hace que una descripción de herramienta MCP sea buena?

De una a tres frases que digan qué hace la herramienta y cuándo llamarla, con las palabras que buscaría un agente cerca del principio. Un parámetro recibe una frase, o nada cuando su nombre, su tipo y sus valores permitidos ya lo dicen. Las reglas, los casos límite y los ejemplos largos van en un documento que el agente lee cuando lo necesita. De todas formas, Claude Code corta a 4.096 caracteres una descripción cargada desde el principio.

¿Cómo evito que las definiciones de herramientas vuelvan a crecer?

Dales un presupuesto que el build pueda comprobar. Tenemos un archivo JSON con un tope total y un tope por herramienta, un script que arranca nuestros servidores MCP, mide cada herramienta y sale con error si se supera cualquiera de los dos límites, y lo ejecutamos antes de cada push. Las herramientas que ya eran demasiado grandes pueden adelgazar, nunca crecer.

En resumen

Tus herramientas MCP son texto que el modelo lee, y nadie revisa ese texto como revisa el código. Mídelo una vez: /context en Claude Code, o el script de arriba para cualquier servidor. Después haz que cada descripción diga qué y cuándo, mueve el cómo a un archivo que el agente lee cuando lo necesita, y pon una cifra en tu build para que no pueda volver a desviarse.

Pasamos de unos 95.000 a unos 38.000 tokens sin quitar una herramienta. Si ejecutas varios agentes con las mismas herramientas, AgentsRoom se descarga gratis, y la página Servidores MCP muestra cómo declarar un servidor una sola vez para todos los CLI y todos los proyectos.