MCP server

Lets an AI agent inspect the financial state of accounts you've assigned to it — balances, transactions, cards, direct debits, standing orders — under the policy you define. Any MCP-compliant client can connect.

# Overview

The agentis MCP server implements Model Context Protocol over Streamable HTTP. See the setup guide for per-client integration steps.

Every session is bound to exactly one agent identity. All tool calls execute against that agent's policy.

# Connection

# Sessions

Sessions follow the MCP Streamable HTTP spec (created on initialize, identified by the Mcp-Session-Id header). Agentis-specific behavior:

• One agent identity per session; concurrent tool calls are permitted within a session
• Sessions are ephemeral; clients should re-initialize on 404 from /mcp (session unknown or expired)

# Authentication

Two flows are supported. Both terminate at the same resource — a Bearer token bound to a single agent identity.

# OAuth 2.0 (Authorization Code + PKCE)

For interactive clients. Standard Authorization Code flow with PKCE (RFC 6749 + 7636); Dynamic Client Registration per RFC 7591.

Supported scopes: mcp. Token endpoint auth method: none.

Unauthenticated requests to /mcp return 401 Unauthorized with a WWW-Authenticate header that points compliant clients at the protected-resource metadata:

WWW-Authenticate: Bearer resource_metadata="https://mcp.agentis.capital/.well-known/oauth-protected-resource"

Token response

POST /token returns the standard OAuth 2.0 token response:

{
  "access_token":  "agts_oat_live_…",
  "token_type":    "Bearer",
  "expires_in":    3600,
  "refresh_token": "agts_ort_live_…",
  "scope":         "mcp"
}

Token lifetimes

Token-endpoint errors follow RFC 6749 §5.2. Only authorization_code and refresh_token grants are accepted.

# Bearer API key

For non-interactive clients. Issue an agent API key from the dashboard and pass it as a Bearer token on every request.

Authorization: Bearer $AGENTIS_API_KEY

Key prefixes

API keys and OAuth tokens carry structured prefixes:

Agent keys do not expire automatically. Revoke or rotate from the dashboard — a revoked key returns 401 on the next call.

# Tools

# Conventions

Tool inputs and outputs are described by JSON schemas returned by tools/list. The reference below covers what each tool is for and when to call it; for the exact request and response shape your agent will see, call tools/list against the live server.

• Tools return an MCP CallToolResult. On success the typed payload is in structuredContent (and serialized as JSON text in content[0].text); on failure isError: true and content[0].text carries the error string — see Errors.
• All monetary amounts are major currency units as decimal strings ("45.50" = EUR 45.50). Currency is a separate ISO 4217 code.
• Dates are YYYY-MM-DD; timestamps are RFC 3339.
• IDs are prefixed ULIDs: agent_…, org_…, pol_…, bnk_…, pay_…, aud_….
• All current tools are idempotent, but every call is a real bank read; banks may rate-limit. The rate_limited structured error (see Errors) is the canonical signal — agents should route on it rather than assume a fixed quota.
• account always defaults to the agent's default bank connection when omitted.
• Fields may be omitted from a response when the agent's data_access policy masks them (e.g. iban, account_holder_name).

# Self-knowledge

# Accounts

# Cards

# Payments

Payment tools will ship soon with Agent Accounts.

# Errors

A tool failure returns an MCP CallToolResult with isError: true. The text in content[0].text takes one of two shapes:

• Short form — Error [code]: message. Used for simple, deterministic failures (e.g. invalid_request, forbidden).
• Structured error object — JSON with the fields below. Used when the failure has a recommended remediation (rate-limit waits, expired consent, transient bank errors).

# Structured error object

The structured error rides inside the standard MCP CallToolResult. A full tools/call response carrying a rate-limit error looks like:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      { "type": "text",
        "text": "{\"reason\":\"rate_limited\",\"action\":\"wait_then_retry\",\"retry_after_seconds\":21600,\"hint\":\"The bank's rate limit on this account has been reached. Suggested wait: ~6 hours before retrying.\"}" }
    ],
    "isError": true
  }
}

# reason and action

Current values listed below. Additions are backwards-compatible; renames or removals trigger a version bump. Route on action to decide the retry strategy; reason tells you why.

# HTTP status codes

Tool-level failures arrive inside CallToolResult with isError: true and a 200 transport status. The transport statuses below have MCP-specific behavior worth handling explicitly — other codes follow RFC 9110.