Referencia técnica MCP

Referencia estricta para implementadores. Sin marketing — solo especificación, endpoints y detalles de conformidad.

Transporte

El gateway MCP habla JSON-RPC 2.0 sobre Streamable HTTP, según spec MCP 2025-11-25.

Patrón de endpoint: https://trusteed.xyz/{storeSlug}/mcp
Tienda demo pública: https://trusteed.xyz/demo-store/mcp
Método: POST application/json (JSON-RPC); GET → 405 Method Not Allowed
Validación Origin/Host: Activa (protección DNS rebinding §3.4 MCP)
Cabecera de versión: MCP-Protocol-Version: 2025-11-25
Streaming: SSE para respuestas streaming; chunked transfer-encoding en operaciones largas

OAuth 2.1 Authorization Code con PKCE S256. Audience binding RFC 8707 obligatorio para tools de escritura.

Audience (resource indicator): https://api.trusteed.xyz
Issuer: https://auth.trusteed.xyz/
JWKS URI: https://auth.trusteed.xyz/.well-known/jwks.json
Algoritmos: RS256 (RSA) con rotación de kid
TTL del token: access 1h, refresh 30d (rotado)
WWW-Authenticate (401): Bearer realm="MCP", resource_metadata="https://api.trusteed.xyz/.well-known/oauth-protected-resource"

Archivos well-known estándar para configuración autónoma de clientes.

/.well-known/oauth-protected-resource: RFC 9728 — metadata del recurso protegido
/.well-known/oauth-authorization-server: RFC 8414 — metadata del servidor de autorización
/.well-known/mcp.json: MCP server card (capabilities, tools, transport)
/.well-known/acp.json: Agent Commerce Protocol discovery
/.well-known/security.txt: RFC 9116 — contacto de seguridad
/llms.txt: Índice del sitio para crawlers LLM
/llms-full.txt: Índice LLM expandido con contenido completo

Los tokens llevan uno o más scopes. Las tools imponen el scope requerido en servidor.

mcp:read: Solo lectura, discovery de producto y merchant. Acceso público en demo store.
mcp:search: Búsquedas wildcard y queries NLWeb.
mcp:write: Mutaciones de cart y checkout (create_cart, select_shipping_option).
mcp:checkout: Liquidación de pedidos (complete_checkout, ucp_complete_checkout).
mcp:admin: Administración de tenant (rotar keys, gestionar agentes).

Límites por tier impuestos en el gateway. 429 con Retry-After (segundos) cuando se exceden.

STARTER20 req/min por agent keyDemo + prototipos de bajo tráfico

GROWTH200 req/min por agent keyAgentes en producción a escala

PRO500 req/min + analíticaOrquestadores multi-merchant

ENTERPRISECustomCapacidad dedicada, consent MCAP

El inventario completo de tools con scopes, efectos secundarios y tier requerido está documentado por separado.

Todos los errores siguen un sobre JSON estable. Construye la lógica de reintento contra el código de error, no el mensaje.