O que o MCP não diz: Cinco primitivas para infraestrutura MCP em produção

MCP te dá três coisas: Client, Server e Transport. A spec é limpa. O SDK funciona. Mas no momento em que você tenta fazer proxy de um server, agregar ferramentas de cinco upstreams, ou fazer sandbox de código de usuário - você está escrevendo centenas de linhas de cola que o protocolo nunca previu.

A Anthropic publicou recentemente "Code Execution with MCP", mostrando que deixar LLMs escrever código contra ferramentas MCP dentro de um sandbox pode reduzir o uso de tokens em 98,7%. Arquitetura interessante. Mas publicaram um conceito, não uma biblioteca.

Estamos rodando esses padrões em produção como parte do deco CMS's control plane MCP open-source. Extraímos cinco primitivas em @decocms/mcp-utils (source). Aqui está o que a spec de MCP deixa de fora - e o código que preenche a lacuna.

As cinco primitivas

Cada primitiva resolve um problema específico que o SDK de MCP não aborda. São pequenas, composáveis, e extraídas do uso em produção - não desenhadas no vácuo.

1. createBridgeTransportPair() - IPC in-process sem overhead

Problema: Você tem um Client e Server no mesmo processo. Os transports do SDK de MCP assumem limites de rede - stdio, SSE, WebSocket. Girar um par de sockets para comunicação in-process é desperdício.

import { createBridgeTransportPair } from "@decocms/mcp-utils";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { Server } from "@modelcontextprotocol/sdk/server/index.js";

const { client: clientTransport, server: serverTransport } = createBridgeTransportPair();

const server = new Server({ name: "my-server", version: "1.0.0" }, { capabilities: { tools: {} } });
const client = new Client({ name: "my-client", version: "1.0.0" });

await server.connect(serverTransport);
await client.connect(clientTransport);

const tools = await client.listTools();

2. createServerFromClient() - Transforme qualquer Client em um Server

Problema: Você precisa fazer proxy de um server MCP remoto - adicionar auth, re-expor em um transport diferente, ou compor em um sistema maior. O SDK não tem o conceito de "wrapp este client como um server."

import { createServerFromClient, createBridgeTransportPair } from "@decocms/mcp-utils";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";

// Conecte a um server MCP upstream
const upstreamClient = new Client({ name: "upstream", version: "1.0.0" });
await upstreamClient.connect(upstreamTransport);

// Exponha como um novo server
const proxyServer = createServerFromClient(upstreamClient, {
  name: "my-proxy",
  version: "1.0.0",
});

// Conecte o proxy a qualquer transport (SSE, stdio, bridge, etc.)
await proxyServer.connect(downstreamTransport);

3. WrapperTransport + composeTransport() - Middleware de Transport

Problema: Você precisa interceptar tráfego MCP para logging, injeção de auth, rate-limiting, ou reescrever requisições. O SDK de MCP trata transports como opacos - não há um modelo de middleware.

import { composeTransport, WrapperTransport } from "@decocms/mcp-utils";
import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";

class LoggingTransport extends WrapperTransport {
  protected handleIncomingMessage(msg: JSONRPCMessage) {
    console.log("←", msg);
    super.handleIncomingMessage(msg);
  }

  protected handleOutgoingMessage(msg: JSONRPCMessage) {
    console.log("→", msg);
    return super.handleOutgoingMessage(msg);
  }
}

class AuthTransport extends WrapperTransport {
  constructor(inner: Transport, private token: string) {
    super(inner);
  }

  protected async handleOutgoingMessage(msg: JSONRPCMessage) {
    // injetar headers de auth, reescrever requisições, etc.
    return super.handleOutgoingMessage(msg);
  }
}

// Componha middlewares - mensagens fluem através de logging, depois auth
const transport = composeTransport(
  baseTransport,
  (t) => new LoggingTransport(t),
  (t) => new AuthTransport(t, "my-token"),
);

4. GatewayClient - Agregação multi-server

Problema: Seu agent precisa de ferramentas de N servers. Carregar todas as definições de ferramentas no contexto da LLM incha o uso de tokens - esse é exatamente o problema que a Anthropic identificou. Mas antes de poder otimizar descoberta de ferramentas, você precisa de um jeito de agregar e rotear entre múltiplos upstreams.

import { GatewayClient } from "@decocms/mcp-utils/aggregate";

const gateway = new GatewayClient({
  slack: { client: slackClient },
  google: { client: googleClient },
  github: { client: () => connectToGithub() }, // lazy - conectado no primeiro uso
});

// Lista ferramentas de todos os upstream servers
const { tools } = await gateway.listTools();

// Chame uma ferramenta - automaticamente roteada para o upstream correto
const result = await gateway.callTool({
  name: "slack_send_message", // namespaced: "{key}_{tool}"
  arguments: { channel: "#general", text: "Hello!" },
});

Allowlists por-client deixam você controlar exatamente o que cada upstream expõe:

const gateway = new GatewayClient({
  slack: {
    client: slackClient,
    tools: ["send_message", "list_channels"], // apenas exponha estas
  },
  github: {
    client: () => connectToGithub(),
    resources: ["repo://main"],               // apenas exponha este recurso
  },
});

5. runCodeWithTools() - Execução de código em sandbox

Problema: A insight chave da Anthropic - deixar LLMs escrever código que chama ferramentas programaticamente, filtrando e transformando dados em um sandbox ao invés de queimar tokens em chamadas de ferramentas multi-turn. Seu blog mostrou uma redução de 98,7% em tokens. Nós shippamos isso como uma função.

import { runCodeWithTools } from "@decocms/mcp-utils/sandbox";

const result = await runCodeWithTools({
  code: `export default async (tools) => {
    const items = await tools.list_items({});
    return items.filter(i => i.status === "active");
  }`,
  client: mcpClient,
  timeoutMs: 5000,
});

console.log(result.returnValue);  // itens filtrados
console.log(result.consoleLogs);  // chamadas console.log/warn/error capturadas

Para controle de nível mais baixo, runCode deixa você injetar funções de ferramenta arbitrárias:

import { runCode } from "@decocms/mcp-utils/sandbox";

const result = await runCode({
  code: `export default async (tools) => {
    const data = await tools.fetch_data({ query: "active" });
    console.log("Found", data.length, "items");
    return data;
  }`,
  tools: {
    fetch_data: async (args) => fetchFromDatabase(args.query),
  },
  timeoutMs: 10_000,
  memoryLimitBytes: 16 * 1024 * 1024, // 16 MB
  stackSizeBytes: 256 * 1024,          // 256 KB
});

Composição - Onde clica

As cinco primitivas são desenhadas para se encaixarem. Aqui está um control plane MCP completo em ~20 linhas:

import { GatewayClient } from "@decocms/mcp-utils/aggregate";
import { createServerFromClient, composeTransport, createBridgeTransportPair } from "@decocms/mcp-utils";

// 1. Agregue múltiplos upstreams
const gateway = new GatewayClient({
  slack: { client: slackClient },
  github: { client: () => connectToGithub() },
  db: { client: dbClient, tools: ["query", "list_tables"] },
});

// 2. Exponha como um server
const server = createServerFromClient(gateway, {
  name: "my-gateway",
  version: "1.0.0",
});

// 3. Adicione middleware e conecte
const transport = composeTransport(
  baseTransport,
  (t) => new LoggingTransport(t),
  (t) => new AuthTransport(t, userToken),
);

await server.connect(transport);

GatewayClient agrega ferramentas de três upstreams. createServerFromClient wrappa o gateway como um server MCP standard. composeTransport coloca camadas de logging e auth. O resultado é um gateway MCP completo com auth, observabilidade e roteamento multi-server - construído de cinco peças composáveis.

Como isso se relaciona com a arquitetura da Anthropic

Essas abordagens são complementares, não em competição. Você poderia usar @decocms/mcp-utils para construir a infraestrutura que a arquitetura da Anthropic fica em cima: GatewayClient agrega seus upstreams, middleware de transport adiciona auth e observabilidade, e runCodeWithTools fornece a camada de sandbox que sua arquitetura requer.

npm install @decocms/mcp-utils @modelcontextprotocol/sdk

Para suporte a sandbox:

npm install quickjs-emscripten-core @jitl/quickjs-wasmfile-release-sync

MCP é um protocolo, não um framework. Essas são as peças que faltam.