Protocolo y transporte MCP

Factuarea admite la revisión de protocolo 2026-07-28 en https://mcp.factuarea.com. Las peticiones usan un sobre JSON-RPC 2.0 sobre HTTP y llevan el contexto del protocolo en cada petición. El servidor no establece una sesión: empieza por server/discover; se rechazan los antiguos initialize y ping. Un cliente que admita una revisión anterior de MCP no es compatible automáticamente.

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 457 herramientas, de las cuales 368 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.

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. Su duración predeterminada es de 120 segundos, con un máximo configurado de 300. 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.