*MCP › Referencia* # Referencia del protocolo > Lo que necesita un cliente para hablar con el servidor sin uno hecho. ## Endpoint y transporte `POST https://app.filmo.io/api/v1/mcp`. 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étodos | 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/initialized` | El cliente lo confirma tras `initialize`. Una petición que solo contiene notificaciones recibe un `202` sin cuerpo. | | `tools/list` | El catálogo. Público sin credencial; con una, solo las herramientas que esta puede llamar. | | `tools/call` | 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 - `Content-Type: application/json` y un `Accept` que incluya `application/json` y `text/event-stream`, como la especificación exige a un cliente. - `Authorization: Bearer ` para `tools/call`. - `MCP-Protocol-Version` en cada petición posterior a `initialize`, con la versión negociada (la especificación se lo pide al cliente). ## Estados HTTP | Estado | Cuándo | Cuerpo | | --- | --- | --- | | 200 | Se procesó un mensaje JSON-RPC, incluido un error de herramienta | Respuesta JSON-RPC | | 401 | `tools/call` sin una credencial válida, o `initialize` o `tools/list` 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.filmo.io` | 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 Un 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 Cada 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].text`, sin `structuredContent`. Un problema 429 lleva `retryAfter` y el `detail` “Rate limit exceeded: retry in N seconds”. Consulta [Errores](https://docs.filmo.io/es/mcp/guides/errors). ## Anotaciones y `_meta` `tools/list` devuelve las cuatro anotaciones (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) y, en 25 herramientas, `_meta["anthropic/requiresUserInteraction"]: true`. Son indicaciones que declara el servidor, no garantías. ## 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].text` | Devuelve el resultado; lee `content[0].text` | | 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/sdk` 1.26.0 y 1.32.1, el cliente de TypeScript `@modelcontextprotocol/client` 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 `structuredContent` porque el SDK de TypeScript 1.x (`callTool`, de 1.20 a 1.32.1) lo valida contra el `outputSchema` aunque `isError` sea `true`. El cliente 2.x y el SDK de Python no lo validan cuando `isError` es `true`; la forma del error pasa en todos ellos. - Un resultado correcto se valida contra el `outputSchema` en ambas líneas de TypeScript, y un campo adicional lanza `-32602 Structured content does not match the tool's output schema`. Por eso el `outputSchema` de cada herramienta está abierto a campos nuevos. - Los errores del SDK de TypeScript 2.x son `ProtocolError` (con un `code`); en 1.x eran `McpError`. Si capturas por clase, comprueba el nombre al migrar. - No probado con el cliente 2.x: el flujo OAuth, el almacenamiento en caché de `tools/list` y los demás cambios de esa línea. Los siete casos se ejecutaron contra dobles de los handlers REST, no contra un servidor desplegado. ## 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. --- URL canónica: https://docs.filmo.io/es/mcp/reference/protocol Última actualización: 2026-10-25