Referencia
Referencia del protocolo
Lo que necesita un cliente para hablar con el servidor sin uno hecho.
Endpoint y transporte
Enlace a esta sección: Endpoint y transportePOST https://. No hay segmento de workspace: la cuenta sale de la credencial. El transporte es Streamable HTTP, solo POST y sin estado: el servidor no asigna ningún Mcp-Session-Id. Un GET responde HTTP 405 con un error JSON-RPC -32000.
| Método | Qué hace |
|---|---|
initialize | Negocia el protocolo. El servidor responde con la revisión que pide el cliente cuando la acepta (consulta Revisiones del protocolo más abajo) y, si no, con 2025-06-18, con la capacidad tools y listChanged: false, y sus instrucciones. |
notifications | El cliente lo confirma tras initialize. Una petición que solo contiene notificaciones recibe un 202 sin cuerpo. |
tools | El catálogo. Público sin credencial; con una, solo las herramientas que esta puede llamar. |
tools | Ejecuta una herramienta. Necesita una credencial. |
ping | Responde {}. Público. |
| Cualquier otra cosa | No se ofrecen prompts ni recursos: el servidor responde -32601. Un lote contiene como máximo 20 mensajes y los ejecuta en orden. |
Cabeceras
Enlace a esta sección: CabecerasContent-Type: applicationy un/json Acceptque incluyaapplicationy/json text, como la especificación exige a un cliente./event-stream Authorization: Bearer <key or access token>paratools./call MCP-Protocol-Versionen cada petición posterior ainitialize, con la versión negociada (la especificación se lo pide al cliente).
Estados HTTP
Enlace a esta sección: Estados HTTP| Estado | Cuándo | Cuerpo |
|---|---|---|
| 200 | Se procesó un mensaje JSON-RPC, incluido un error de herramienta | Respuesta JSON-RPC |
| 401 | tools sin una credencial válida, o initialize o tools con una credencial que no es válida | Problema RFC 9457, con WWW-Authenticate (resource_metadata, scope) |
| 405 | GET | Error JSON-RPC -32000 |
| 308 | Un host de producción que no es app. | Un error JSON-RPC que nombra la URL canónica |
| 500 | Un fallo inesperado | Error JSON-RPC -32603 |
Un límite impuesto por la plataforma (413, 502, 504) no es un documento de problema.
Errores JSON-RPC
Enlace a esta sección: Errores JSON-RPCUn fallo de protocolo es un error JSON-RPC con los códigos estándar (-32700 análisis, -32600 petición no válida, -32601 método no encontrado, -32602 parámetros no válidos o herramienta desconocida, -32603 interno). Los mensajes están en inglés. Una llamada fallida no es uno de estos: consulta más abajo.
El resultado de una herramienta
Enlace a esta sección: El resultado de una herramientaCada herramienta declara un outputSchema, abierto a campos nuevos. Un éxito devuelve structuredContent con data (y pagination en los listados) y meta:
campo meta | Cuándo |
|---|---|
idempotencyKey | Una escritura que lleva una clave: la tuya; en las cuatro herramientas que duplican algo irreversible ante un reintento a ciegas, la que genera el servidor si no enviaste ninguna |
idempotentReplay | true cuando la llamada repite una anterior con la misma clave y no se volvió a ejecutar nada |
rateLimit | Siempre: { limit, remaining, reset }, lo que dicen las cabeceras RateLimit-* en REST |
etag | Una lectura de detalle: pásalo como ifMatch en la siguiente escritura |
Un fallo es un resultado con isError: true y el problema RFC 9457 como JSON en content[0]., sin structuredContent. Un problema 429 lleva retryAfter y el detail “Rate limit exceeded: retry in N seconds”. Consulta Errores.
Anotaciones y _meta
Enlace a esta sección: Anotaciones y _metatools devuelve las cuatro anotaciones (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) y, en 25 herramientas, _meta["anthropic. Son indicaciones que declara el servidor, no garantías.
Qué hacen los SDK oficiales
Enlace a esta sección: Qué hacen los SDK oficiales| Resultado | callTool del SDK de TypeScript | call_tool del SDK de Python |
|---|---|---|
Éxito con meta | Devuelve el resultado | Devuelve el resultado |
Error de herramienta (isError) | Devuelve el resultado; lee content[0]. | Devuelve el resultado; lee content[0]. |
| A 429 | Devuelve el resultado; retryAfter en el problema | Devuelve el resultado; retryAfter en el problema |
| Herramienta desconocida, petición incorrecta | Lanza (error JSON-RPC) | Lanza |
Filmo ejecutó siete casos contra la ruta real (una lectura, una escritura con idempotencyKey, una repetición con la misma clave, un 400, un 403 insufficient_scope, un 404 y un 429) con el SDK de TypeScript @modelcontextprotocol 1.26.0 y 1.32.1, el cliente de TypeScript @modelcontextprotocol 2.3.1 y el SDK de Python mcp 1.27.1 y 2.3.0. Ninguno lanza -32602 y el problema del 429 llega legible. Client y StreamableHTTPClientTransport se usan igual en las dos líneas de TypeScript; solo cambian el paquete y el import. No se probaron otras versiones.
- Un error de herramienta no tiene
structuredContentporque el SDK de TypeScript 1.x (callTool, de 1.20 a 1.32.1) lo valida contra eloutputSchemaaunqueisErrorseatrue. El cliente 2.x y el SDK de Python no lo validan cuandoisErrorestrue; la forma del error pasa en todos ellos. - Un resultado correcto se valida contra el
outputSchemaen ambas líneas de TypeScript, y un campo adicional lanza-32602 Structured content does not match the tool's output schema. Por eso eloutputSchemade cada herramienta está abierto a campos nuevos. - Los errores del SDK de TypeScript 2.x son
ProtocolError(con uncode); en 1.x eranMcpError. Si capturas por clase, comprueba el nombre al migrar. - No probado con el cliente 2.x: el flujo OAuth, el almacenamiento en caché de
toolsy los demás cambios de esa línea. Los siete casos se ejecutaron contra dobles de los handlers REST, no contra un servidor desplegado./list
Revisiones del protocolo
Enlace a esta sección: Revisiones del protocolo| Revisión | Notas |
|---|---|
2025-06-18 | El valor por defecto: el servidor lo responde cuando el cliente lo pide o pide una revisión que el servidor no conoce. |
2025-03-26, 2024-11-05 | Aceptado: el servidor responde con la misma revisión que pidió el cliente. |
2025-11-25 | No está en la lista del servidor, así que responde a initialize con el valor por defecto, como permite el ciclo de vida de esa revisión; un cliente que no pueda usar el valor por defecto se desconecta. |
2026-07-28 | La revisión actual de la especificación. No guarda estado y no tiene initialize; la mayoría de los clientes aún usan el handshake anterior. |
El servidor no anuncia los documentos de metadatos de ID de cliente (CIMD), que la especificación más reciente prefiere al registro dinámico. Fuentes: modelcontextprotocol.io/specification/versioning y /specification/2026-07-28/basic/versioning, consultadas el 2026-10-25.
Páginas relacionadas
Enlace a esta sección: Páginas relacionadasGuías
Errores
Un error de herramienta es un resultado con
isError: truey el problema en el primer bloque de texto. Ramifica por sucode.Conectar
Crea tu propio cliente
Usa los SDK oficiales de MCP o los conectores MCP de las APIs de Anthropic y OpenAI.
Introducción
Servidor MCP
Conecta un asistente de IA a tu cuenta de Filmo. Puede usar exactamente las herramientas que permita su clave o su conexión.
¿Te ha resultado útil esta página?