*MCP › 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.

MCP (Model Context Protocol) permite que un asistente llame a herramientas. El servidor de Filmo convierte la API REST en 170 herramientas entre las que un asistente puede elegir mientras responde. Cada herramienta ejecuta una operación REST con la misma clave, los mismos scopes, los mismos límites de peticiones y la misma cuenta, así que todo lo que sabes de la API REST se aplica.

- 76 herramientas de lectura consultan datos: pedidos, artículos, contactos, facturas, el calendario.
- 94 herramientas de escritura o de consulta con IA cambian la cuenta o gastan créditos. Los clientes deberían preguntar antes de ejecutarlas.
- 34 están anotadas como destructivas, 25 están marcadas para preguntar a una persona en cada llamada y 35 están en la lista para poner en «preguntar antes de ejecutar»: consulta [Escrituras seguras](https://docs.filmo.io/es/mcp/guides/safe-writes#requires-confirmation).

## Qué puedes preguntar

- «¿Qué pedidos empiezan mañana y para qué clientes?»
- «¿Hay dos unidades de este objetivo libres del 15 al 17 de enero?»
- «Crea un pedido en borrador para este cliente y deja una nota para la puerta norte.»

## Autenticación

| Método | Úsalo cuando | Página |
| --- | --- | --- |
| Clave de API en `Authorization: Bearer` | El cliente envía cabeceras: Claude Code, Cursor, VS Code, Windsurf, Codex, Gemini CLI, Make, n8n, tu propio código. | Conectar |
| OAuth 2.1 con PKCE | El cliente inicia sesión por ti: Claude, ChatGPT y los clientes anteriores cuando lo prefieras. Un administrador da su consentimiento. | Autenticación |

Una llamada sin credencial recibe un HTTP 401 que apunta a los metadatos de OAuth; la URL de arriba es la única que hay que usar.

## Qué le dice el servidor al asistente

Cuando un cliente se conecta, el servidor envía instrucciones: fechas, dinero, claves de idempotencia, bloqueo optimista, límites de peticiones, paginación y cómo llegan los errores. Hay dos variantes. Sin credencial es el texto genérico de abajo. Con credencial añade un resumen de lo que esa clave puede leer y escribir, y la zona horaria, la moneda y el país de la cuenta. Lo esencial va primero, en los primeros 2,048 caracteres, porque algunos clientes cortan las instrucciones ahí.

**Instrucciones sin credencial**

```text
Filmo public API (rental management for audiovisual equipment). Every tool maps to one REST v1 operation and runs with the same credential, scopes, rate limits and tenancy as the REST endpoint.

Retries: writes accept idempotencyKey; resend the same key to retry safely (same key with other arguments: 422 idempotency_key_reused). 4 tools (filmo_orders_line_items_return, filmo_purchase_orders_receive, filmo_treasury_payments_create, filmo_workflows_run) duplicate something irreversible on a blind retry: always send your own UUID with them. Results echo the key in meta.idempotencyKey (the server generates one for those 4 if you omit it), and meta.idempotentReplay is true when you got the stored result of an earlier call.

Errors: a failed call returns isError and, as text, the RFC 9457 problem JSON { type, title, status, code, detail, requestId, errors? }. Branch on code, not on detail. 429 rate_limited carries retryAfter (seconds to wait).

Dates: writes take instants as ISO 8601 with offset; responses use UTC ("Z"). In list tools use dateFilters: { field: { gte, lte, gt, lt, on } }; there a bare day ("2026-10-17") is interpreted in the business timezone of the account: the start of that day for gte/on, the end of that day for lte; gt means after the end of that day, lt before its start. An instant with offset is applied as is, except with on, which covers the whole business day that contains it.

Money: decimal strings ("1234.50") plus the currency of the document. Ids are opaque strings. Detail reads return meta.etag; pass it as ifMatch on a write to get 412 precondition_failed instead of overwriting a newer change.

No credential was presented during discovery, so this list is the full catalogue: at call time each tool requires the scope named in its description, and some require an add-on on the account.

Rate limits: 120 calls per minute per credential across all tools, plus a separate 30 per minute shared by the availability tools. Every result carries the quota left in meta.rateLimit { limit, remaining, reset }.

Lists are paginated: pass pagination.nextCursor back as cursor, keeping the same limit (default 50, maximum 500); set includeTotal to true when you need pagination.total; every list tool but the unavailabilities one accepts sort, a comma-separated list of fields with a leading "-" for descending (the tool description names the sortable fields), and the cursor is bound to it.

Error codes: unauthorized and the api_key_* codes (401), insufficient_scope (403) with requiredScope, forbidden (403), addon_required (402) with requiredAddon, validation_error (400, with every field error in errors[]), not_found (404), conflict (409), contact_in_use and address_in_use (409, what uses it counted per type in errors[]), insufficient_stock (409, requested/available/shortfall per item in errors[]), precondition_failed (412), idempotency_key_reused (422), rate_limited (429, with retryAfter), internal_error (500), service_unavailable (503: the feature is switched off for the account; retrying does not help until it is switched on). detail and errors[].message follow the Accept-Language of the MCP request; quote requestId when reporting a problem.
```

## Conectar un cliente

- **[Claude](https://docs.filmo.io/es/mcp/connect/claude)**: Añade Filmo a Claude en la web o en la app de escritorio como conector personalizado.
- **[Claude Code](https://docs.filmo.io/es/mcp/connect/claude-code)**: Añade Filmo a Claude Code con OAuth o con una clave de API que se queda fuera de tu repositorio.
- **[ChatGPT](https://docs.filmo.io/es/mcp/connect/chatgpt)**: Añade Filmo a ChatGPT como servidor MCP personalizado. ChatGPT se conecta solo con OAuth.
- **[Cursor](https://docs.filmo.io/es/mcp/connect/cursor)**: Añade Filmo a Cursor con OAuth o con una clave de API leída de tu entorno.
- **[VS Code](https://docs.filmo.io/es/mcp/connect/vscode)**: Añade Filmo a VS Code (modo agente de GitHub Copilot) con OAuth o con una clave de API que él mismo te pide.
- **[Windsurf](https://docs.filmo.io/es/mcp/connect/windsurf)**: Añade Filmo al Cascade de Windsurf con una clave de API leída de tu entorno.
- **[OpenAI Codex](https://docs.filmo.io/es/mcp/connect/codex)**: Añade Filmo a Codex (CLI e IDE) con OAuth o con una clave de API leída de una variable de entorno.
- **[Gemini CLI](https://docs.filmo.io/es/mcp/connect/gemini-cli)**: Añade Filmo a Gemini CLI con OAuth o con una clave guardada en tu archivo de ajustes de usuario.
- **[Make](https://docs.filmo.io/es/mcp/connect/make)**: Llama a las herramientas de Filmo desde un escenario de Make con la app MCP Client.
- **[n8n](https://docs.filmo.io/es/mcp/connect/n8n)**: Da a un AI Agent de n8n las herramientas de Filmo con el nodo MCP Client Tool.
- **[Otros clientes](https://docs.filmo.io/es/mcp/connect/other-clients)**: Zapier, Raycast, GitHub Copilot, Obsidian, MCP Inspector y cualquier cliente que hable MCP sobre HTTP.
- **[Construir el tuyo](https://docs.filmo.io/es/mcp/connect/build-your-own)**: Usa los SDK oficiales de MCP o los conectores MCP de las APIs de Anthropic y OpenAI.

El contrato de esta página es la instantánea de 170 operaciones REST y 170 herramientas tomada el 2026-10-25.

## Servidor

*URL del servidor*

```text
https://app.filmo.io/api/v1/mcp
```

Transporte: Streamable HTTP

| Dato | Valor |
| --- | --- |
| Transporte | Streamable HTTP, solo POST; sin estado, sin `Mcp-Session-Id`. |
| Revisión del protocolo | `2025-06-18` |
| Estado | Versión del servidor `1.0.0+b96c787e2203`. |
| Catálogo | 170 herramientas, públicas en `tools/list`; con una clave, solo las que la clave puede llamar. |
| Autenticación | Clave de API en la cabecera, u OAuth 2.1 con PKCE y registro dinámico. |
| Relación con REST | Cada herramienta ejecuta exactamente una operación REST, con la misma clave, permisos, límites y cuenta. |
| Capacidades | Solo herramientas: no hay prompts ni recursos. |

## Permisos

| Permiso | Permite |
| --- | --- |
| `*:read` | 31 permisos de lectura, 76 herramientas. Listar y obtener registros. |
| `*:write` | 26 permisos de escritura, 92 herramientas. Crear, cambiar y borrar. |
| `workflows:run` | Ejecutar un workflow. |
| `ai:ask` | Preguntar a la IA de la cuenta. Gasta créditos de IA. |

## Conecta un cliente

**Command**

```bash
claude mcp add --transport http filmo --scope user https://app.filmo.io/api/v1/mcp \
  --header "Authorization: Bearer $FILMO_API_KEY"
```

**mcp.json**

```json
{
  "mcpServers": {
    "filmo": {
      "url": "https://app.filmo.io/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:FILMO_API_KEY}"
      }
    }
  }
}
```

**.vscode/mcp.json**

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "filmo-api-key",
      "description": "Filmo API key",
      "password": true
    }
  ],
  "servers": {
    "filmo": {
      "type": "http",
      "url": "https://app.filmo.io/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${input:filmo-api-key}"
      }
    }
  }
}
```

**mcp_config.json**

```json
{
  "mcpServers": {
    "filmo": {
      "serverUrl": "https://app.filmo.io/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:FILMO_API_KEY}"
      }
    }
  }
}
```

**~/.codex/config.toml**

```text
[mcp_servers.filmo]
url = "https://app.filmo.io/api/v1/mcp"
bearer_token_env_var = "FILMO_API_KEY"
```

**~/.gemini/settings.json**

```json
{
  "mcpServers": {
    "filmo": {
      "httpUrl": "https://app.filmo.io/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer <your-filmo-api-key>"
      }
    }
  }
}
```

**mcp-remote**

```json
{
  "command": "npx",
  "args": [
    "-y",
    "mcp-remote",
    "https://app.filmo.io/api/v1/mcp",
    "--header",
    "Authorization:${FILMO_AUTH}"
  ],
  "env": {
    "FILMO_AUTH": "Bearer ${FILMO_API_KEY}"
  }
}
```

---

URL canónica: https://docs.filmo.io/es/mcp/overview  
Última actualización: 2026-10-25