Protocol i transport MCP

Factuarea admet la revisió de protocol 2026-07-28 a https://mcp.factuarea.com. Les peticions fan servir un embolcall JSON-RPC 2.0 sobre HTTP i porten el context del protocol a cada petició. El servidor no estableix cap sessió: comença per server/discover; es rebutgen els antics initialize i ping. Un client que admeti una revisió anterior de MCP no és compatible automàticament.

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é 457 eines, de les quals 368 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.

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. La durada predeterminada és de 120 segons, amb un màxim configurat de 300. 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.