MCP protocol and transport

Factuarea implements protocol revision 2026-07-28 at https://mcp.factuarea.com and keeps serving clients on 2025-11-25 and 2025-06-18. Requests use a JSON-RPC 2.0 envelope over Streamable HTTP. The server never keeps a session: every request carries its own credential and, in the current revision, its own protocol context. Current clients start with server/discover; clients on an earlier revision start with initialize (see below).

First request

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

Send MCP-Protocol-Version and Mcp-Method on every call, matching the envelope. For named operations such as tools/call and prompts/get, add Mcp-Name matching params.name; resource reads identify the resource URI. Keep the _meta protocol version, capabilities and client information in each request. Authenticate every call with an API key or OAuth access token.

Discover and call

After server/discover, use tools/list, resources/list and prompts/list. Tool discovery is filtered by credential scopes and channel policy: the complete catalog has 668 tools, of which 541 are OAuth-reachable. Always use the returned schema; a tool hidden from your credential is not made available by knowing its name.

Successful results use the revision’s resultType: complete shape. Inspect error envelopes and tool errors separately; a protocol lookup failure and a business rejection have different remedies. Irreversible operations enforce idempotency_key according to their policy even when the input schema marks it optional. Replayed calls can return com.factuarea/idempotentReplay metadata.

Clients on earlier revisions

Clients that implement 2025-11-25 or 2025-06-18 negotiate with initialize and then use ping, tools/list, tools/call, prompts/* and resources/* as usual. The handshake does not create a session or replace the credential: each request is still authenticated, filtered by scopes, plan and modules, and subject to the same guardrails and idempotency policy. The server offers no HTTP+SSE transport and no GET event stream, so send every call as POST. A request that carries any metadata of the current revision is treated as a current-revision request and must include all of it.

Pagination and caching

Follow opaque nextCursor values while retaining the same credential and request context. Cursors expire; restart discovery when one becomes invalid. A tools/list cursor lasts 24 hours (configurable, with a ceiling of 7 days). It is tied to the identity that received it, not to the token: the API key or, with OAuth, the company, user and OAuth client together. Renewing the access token with the refresh token does not invalidate it, and a different identity cannot use it. If the visible catalog changes between pages (a deployment, or a change of scopes, modules or plan), you get no error: the server returns the first page of the current catalog, and it does the same with a cursor from the former format. Without per_page, the first response already carries the whole catalog (the default page is large enough for the whole public catalog, about 668 tools), so a client that does not paginate receives every tool and no nextCursor. Respect returned cache hints and their private scope; never reuse another company’s or credential’s tool list. Default discovery/resource cache hints are 60 seconds, but the response is authoritative.