Protocolo y transporte MCP

Factuarea implementa la revisión de protocolo 2026-07-28 en https://mcp.factuarea.com y sigue atendiendo a clientes en 2025-11-25 y 2025-06-18. Las peticiones usan un sobre JSON-RPC 2.0 sobre Streamable HTTP. El servidor nunca mantiene una sesión: cada petición lleva su propia credencial y, en la revisión actual, su propio contexto de protocolo. Los clientes actuales empiezan por server/discover; los de una revisión anterior, por initialize (consulta más abajo).

Primera petición

curl https://mcp.factuarea.com \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: server/discover" \
  --data '{
  "jsonrpc": "2.0",
  "id": "discover-1",
  "method": "server/discover",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {},
      "io.modelcontextprotocol/clientInfo": {
        "name": "erp-factuarea",
        "version": "1.0.0"
      }
    }
  }
}'

Envía MCP-Protocol-Version y Mcp-Method en cada llamada, coincidiendo con el sobre. En operaciones con nombre como tools/call y prompts/get, añade Mcp-Name con el valor de params.name; las lecturas de recursos identifican su URI. Conserva en cada petición la versión de protocolo, capacidades e información del cliente en _meta. Autentica cada llamada con una API key o un token de acceso OAuth.

Descubre e invoca

Después de server/discover, usa tools/list, resources/list y prompts/list. El descubrimiento de herramientas se filtra por los scopes de la credencial y la política del canal: el catálogo completo tiene 668 herramientas, de las cuales 541 son accesibles por OAuth. Usa siempre el esquema recibido; conocer el nombre de una herramienta oculta para tu credencial no la habilita.

Los resultados correctos usan la forma resultType: complete de esta revisión. Distingue los errores del sobre y los errores de herramienta; un fallo de búsqueda del protocolo y un rechazo de negocio requieren actuaciones distintas. Las operaciones irreversibles exigen idempotency_key según su política aunque el esquema de entrada lo marque opcional. Las llamadas reproducidas pueden incluir metadatos com.factuarea/idempotentReplay.

Clientes con revisiones anteriores

Los clientes que implementan 2025-11-25 o 2025-06-18 negocian con initialize y después usan ping, tools/list, tools/call, prompts/* y resources/* con normalidad. El saludo inicial no crea una sesión ni sustituye a la credencial: cada petición se sigue autenticando, se filtra por scopes, plan y módulos, y se somete a los mismos guardrails y a la misma política de idempotencia. El servidor no ofrece el transporte HTTP+SSE ni un flujo de eventos por GET, así que envía cada llamada con POST. Una petición que incluya cualquier metadato de la revisión actual se trata como de la revisión actual y debe incluirlos todos.

Paginación y caché

Sigue los valores opacos de nextCursor manteniendo la misma credencial y contexto. Los cursores caducan; reinicia el descubrimiento cuando uno deje de ser válido. El cursor de tools/list dura 24 horas (configurable, con un tope de 7 días). Va ligado a la identidad que lo recibió, no al token: la API key o, con OAuth, la empresa, el usuario y el cliente OAuth a la vez. Renovar el access token con el refresh token no lo invalida, y otra identidad no puede usarlo. Si entre páginas cambia el catálogo visible (un despliegue, o un cambio de scopes, módulos o plan), no recibes ningún error: el servidor devuelve la primera página del catálogo actual, y lo mismo ocurre con un cursor del formato anterior. Sin per_page, la primera respuesta ya incluye el catálogo completo (la página predeterminada basta para todo el catálogo público, unas 668 tools), así que un cliente que no pagine recibe todas las tools y ningún nextCursor. Respeta las indicaciones de caché y su ámbito privado; nunca reutilices la lista de herramientas de otra empresa o credencial. Las indicaciones predeterminadas de caché para discovery y recursos son de 60 segundos, pero prevalece la respuesta.