MCP

Veriticity exposes a Model Context Protocol endpoint so an AI assistant can check, request and follow up on purchases — within the spending rules a person set, and acting as an agent that already exists.

POST https://app.veriticity.com/mcp

Streamable HTTP, stateless. Nothing is remembered between calls, which is correct for a multi-instance deployment and means one caller’s session can never be served to another.

How an assistant connects#

MCP uses the same OAuth boundary as the rest of the API — not a second authentication model. An access token from a connection a person authorised is the only credential accepted; an API key is refused outright.

The discovery chain is standard, so most clients do it for you:

# An unauthenticated call tells a client where to authenticate.
curl -i -X POST https://app.veriticity.com/mcp

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://app.veriticity.com/.well-known/oauth-protected-resource/mcp"

{
  "resource": "https://app.veriticity.com/mcp",
  "authorization_servers": ["https://app.veriticity.com"],
  "scopes_supported": ["purchase:check", "purchase:request", "purchase:read"],
  "bearer_methods_supported": ["header"]
}

From there the client fetches the authorization server’s own metadata and runs Authorization Code with PKCE. A person signs in, chooses the organisation and the agent, and approves the scopes. See Authentication for the full flow.

The eight tools#

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "check_purchase",
    "arguments": {
      "merchant": "Acme Cloud",
      "amountMinor": "7500",
      "currency": "GBP"
    }
  }
}

Three scopes across eight tools is not a gap. The vocabulary describes what a person consented to, not how many functions the transport exposes — reading what is left of a budget is the same grant as asking whether a purchase would be allowed, because it is that question with the purchase left out.

Paging through history#

list_purchases uses keyset cursor pagination: limit between 1 and 50, defaulting to 20, and a nextCursor to carry forward. This is deliberately not the page-and-size model GET /v1/policies uses; see Conventions.

What an assistant cannot do#

Each absence is a design decision rather than a missing feature.

• No tool approves, rejects, resolves or overrides an approval. When the engine escalates, a person answers in the dashboard and the assistant finds out by calling get_purchase. An assistant that could answer its own escalation would make the human half of the trust layer decorative.
• No tool writes, activates or archives a policy. The rules an agent is judged against are not editable by the thing being judged.
• No tool creates, renames, disables or archives an agent, and none issues, reads or revokes a credential or a connection.
• No tool enumerates the organisation’s agents. An agent handed a roster of its organisation’s other agents has been handed a map of the identities it might impersonate. get_agent describes the one agent the caller already is.
• No tool reads the authoring model — no drafts, no version history, no assignment lists. get_spending_rules reports what is in force, not how somebody arrived at it.
• No generic passthrough. There is no tool that forwards an arbitrary request to /v1.
• No tool moves money. Veriticity governs purchase decisions; it does not execute payments.

Identity comes from the connection#

No tool accepts organizationId, agentId or connectionId. Not validated, not ignored — absent from every schema, so an assistant that tries to send one gets a schema violation from the protocol layer and there is no code path on which the value could be consulted.

Both come from the authenticated connection. An assistant that could choose its own agent would be choosing whose money it was about to spend.

Every read is narrowed on the submitting connection inside the query. Another connection’s purchases — even another connection to the same agent — are indistinguishable from purchases that do not exist.

Retries and idempotency#

A tool call carries no Idempotency-Key convention, so request_purchase derives one from the connection and the canonical arguments. A host that retries a timed-out call replays the original decision instead of making a second purchase.

That means calling request_purchase twice with identical arguments is one purchase. If an assistant genuinely wants two, the arguments have to differ — which is usually true anyway, since reason is part of the key.

Errors and refusals#

Tools return structuredContent as well as text, so a client that wants fields gets fields. There are deliberately no declared output schemas: the shapes come from the same builders the REST API uses, and a second hand-maintained description of them would drift.

If a connection lacks a scope, the tool answers with the same insufficient_scope distinction the REST API uses — re-authorising with a wider grant will work. See Errors.