Protocol i transport MCP

Factuarea implementa la revisió de protocol 2026-07-28 a https://mcp.factuarea.com i continua atenent clients a 2025-11-25 i 2025-06-18. Les peticions fan servir un embolcall JSON-RPC 2.0 sobre Streamable HTTP. El servidor no manté mai cap sessió: cada petició porta la seva pròpia credencial i, a la revisió actual, el seu propi context de protocol. Els clients actuals comencen per server/discover; els d’una revisió anterior, per initialize (consulta més avall).

Primera petició

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"
      }
    }
  }
}'

Envia MCP-Protocol-Version i Mcp-Method a cada crida, coincidint amb l’embolcall. En operacions amb nom com tools/call i prompts/get, afegeix Mcp-Name amb el valor de params.name; les lectures de recursos identifiquen la seva URI. Conserva a cada petició la versió de protocol, les capacitats i la informació del client a _meta. Autentica cada crida amb una API key o un token d’accés OAuth.

Descobreix i invoca

Després de server/discover, fes servir tools/list, resources/list i prompts/list. El descobriment d’eines es filtra pels scopes de la credencial i la política del canal: el catàleg complet té 668 eines, de les quals 541 són accessibles per OAuth. Fes servir sempre l’esquema rebut; conèixer el nom d’una eina oculta per a la teva credencial no l’habilita.

Els resultats correctes fan servir la forma resultType: complete d’aquesta revisió. Distingeix els errors de l’embolcall i els errors d’eina; un error de cerca del protocol i un rebuig de negoci requereixen actuacions diferents. Les operacions irreversibles exigeixen idempotency_key segons la seva política encara que l’esquema d’entrada el marqui opcional. Les crides reproduïdes poden incloure metadades com.factuarea/idempotentReplay.

Clients amb revisions anteriors

Els clients que implementen 2025-11-25 o 2025-06-18 negocien amb initialize i després fan servir ping, tools/list, tools/call, prompts/* i resources/* amb normalitat. La salutació inicial no crea cap sessió ni substitueix la credencial: cada petició continua autenticant-se, es filtra per scopes, pla i mòduls, i se sotmet als mateixos guardrails i a la mateixa política d’idempotència. El servidor no ofereix el transport HTTP+SSE ni cap flux d’esdeveniments per GET, així que envia cada crida amb POST. Una petició que inclogui qualsevol metadada de la revisió actual es tracta com de la revisió actual i les ha d’incloure totes.

Paginació i memòria cau

Segueix els valors opacs de nextCursor mantenint la mateixa credencial i context. Els cursors caduquen; reinicia el descobriment quan un deixi de ser vàlid. El cursor de tools/list dura 24 hores (configurable, amb un topall de 7 dies). Va lligat a la identitat que el va rebre, no al token: l’API key o, amb OAuth, l’empresa, l’usuari i el client OAuth alhora. Renovar l’access token amb el refresh token no l’invalida, i una altra identitat no el pot fer servir. Si entre pàgines canvia el catàleg visible (un desplegament, o un canvi d’scopes, mòduls o pla), no reps cap error: el servidor retorna la primera pàgina del catàleg actual, i el mateix passa amb un cursor del format anterior. Sense per_page, la primera resposta ja inclou el catàleg complet (la pàgina predeterminada n’hi ha prou per a tot el catàleg públic, unes 668 tools), de manera que un client que no pagini rep totes les tools i cap nextCursor. Respecta les indicacions de memòria cau i el seu àmbit privat; no reutilitzis mai la llista d’eines d’una altra empresa o credencial. Les indicacions predeterminades de memòria cau per a discovery i recursos són de 60 segons, però preval la resposta.