Connect AI Agents to Idem via the MCP Server

Idem exposes its agentic execution layer over the Model Context Protocol as well as REST. Any MCP-compatible agent — Claude Desktop, Claude Code, or a custom runtime — can post transactions, query balances, list entries, reconcile settlements, and roll back workflows without a custom API integration. Every tool call goes through the same stack as a REST request: scope-checked authentication, PolicyGuard evaluation before any write, and an HMAC-signed, append-only audit entry recorded before execution.

MCP tool calls are subject to the same policy rules and scopes as REST requests. An agent key that can postTransaction is not automatically permitted to rollbackWorkflow — see Required scopes below.

How a tool call flows through Idem

AI agent (Claude Desktop / Claude Code / custom)
    │  MCP JSON-RPC 2.0 over SSE
    ▼
Session auth bridge  →  injects your tenant's authentication into the request
    │
Scope check  →  hasAuthority('AGENTS_EXECUTE' | 'AGENTS_ROLLBACK' | 'AGENTS_AUDIT_READ')
    │
MCP tool method
    │
PolicyGuard.evaluate()  ←  policy rules loaded per tenant + agent key prefix
    │
Ledger use case (execute / query / reconcile / rollback)
    │
PostgreSQL (journal_lines, transactions, accounts)

Connect over SSE

The MCP server exposes two endpoints on your Idem instance:

Endpoint	Method	Purpose
`/sse`	`GET`	Opens the SSE stream and returns a session ID
`/mcp/messages`	`POST`	Sends JSON-RPC 2.0 tool-call messages; requires `?sessionId=<uuid>` from the `/sse` handshake

Authenticate the same way you would for REST — an X-API-Key header or Authorization: Bearer — on the initial GET /sse request. You don’t need to resend the key on each POST /mcp/messages call; Idem associates your session with your authenticated tenant for the lifetime of the SSE connection.

Required scopes

Most tools require AGENTS_EXECUTE. Rolling back a workflow and reading the audit log each require their own separate scope — an agent authorized to execute transactions cannot roll them back or read the audit trail unless explicitly granted those scopes too.

Tool	Required scope
`postTransaction`	`AGENTS_EXECUTE`
`getBalance`	`AGENTS_EXECUTE`
`listEntries`	`AGENTS_EXECUTE`
`describeAccount`	`AGENTS_EXECUTE`
`reconcileBatch`	`AGENTS_EXECUTE`
`rollbackWorkflow`	`AGENTS_ROLLBACK`
`getAgentAuditLog`	`AGENTS_AUDIT_READ`

See Scopes for the full scope reference and how to issue a least-privilege agent key.

Tools

`postTransaction`

Posts a balanced double-entry transaction as an AI agent.

postTransaction(
    entries: List<JournalLine>,   // journal lines — see below
    idempotencyKey: string,       // duplicate calls with the same key return the cached result
    intentDescription?: string,   // human-readable intent, recorded in the audit log
    agentId: string,              // agent identifier from your credentials
    sessionId: string,            // session grouping related agent actions
) → { workflowPlanId: string, status: string }

Each entry in entries:

Field	Required	Notes
`accountId`	Yes	UUID of the account
`entryType`	Yes	`DEBIT` or `CREDIT`
`monetaryEntryType`	Yes	`FIAT` or `ON_CHAIN`
`amount`	Yes	Decimal string, e.g. `"1000.00"`
`currency`	FIAT only	ISO 4217: `BRL`, `USD`, `MXN`, `EUR`
`rail`	FIAT only	`ACH`, `WIRE`, `PIX`, `SWIFT`, `SEPA`
`bankReference`	Optional	Bank-issued reference
`token`	ON_CHAIN only	`USDC`, `USDT`, `BRZ`, `PYUSD`
`chainId`	ON_CHAIN only	`EVM`, `SOLANA`, `TRON`
`txHash`	ON_CHAIN only	On-chain transaction hash
`blockNumber`	ON_CHAIN only	Block number
`walletAddress`	ON_CHAIN only	Receiving wallet address
`tokenContract`	ON_CHAIN only	Token contract address

PolicyGuard evaluates the effective policy rules for your tenant and agent key prefix before the transaction commits. If no rules are configured for an agent, the default is deny-all — configure at least one permissive rule before an agent can post a debit.

`getBalance`

Returns the current balance for an account, optionally as of a point in time.

getBalance(
    accountId: string,   // account UUID
    asOf?: string,        // ISO-8601 instant, e.g. "2025-12-31T23:59:59Z"
) → { accountId: string, currency: string, amount: string, computedAt: string, onChainBalances: OnChainBalanceItem[] }

onChainBalances is a per-token breakdown of on-chain entries posted to the account, net across all chains for that token. Each OnChainBalanceItem is { token, amount }. It is never combined with the fiat amount above — a token amount and a fiat amount are not fungible units. An account with only fiat entries returns onChainBalances: [].

`listEntries`

Lists journal entries for an account, newest first, with time-range filtering and cursor-based pagination.

listEntries(
    accountId: string,
    from?: string,     // ISO-8601 inclusive lower bound
    to?: string,       // ISO-8601 inclusive upper bound
    limit?: number,    // 1–200, default 50
    cursor?: string,   // opaque cursor from a previous page's nextCursor
) → { accountId: string, entries: EntryItem[], nextCursor?: string }

Each EntryItem includes id, transactionId, entryType, amount, currency (ISO 4217 for fiat, token symbol for on-chain), description, and createdAt.

`describeAccount`

Returns account metadata and current balance in a single call.

describeAccount(
    accountId: string,
) → {
      accountId: string, name: string, description?: string, currency: string,
      entryCount: number, lastActivityAt?: string,
      balanceCurrency: string, balanceAmount: string
    }

`reconcileBatch`

Runs a reconciliation sweep over on-chain settlements within a time window, matching unmatched chain entries against pending journal lines by amount.

reconcileBatch(
    accountId?: string,          // optional account UUID to scope the sweep
    from: string,                // ISO-8601 lower bound on settlement timestamp
    to: string,                  // ISO-8601 upper bound on settlement timestamp
    tolerancePercent?: number,   // optional per-call override of the server default
) → { matched: number, unmatched: number, exceptions: string[], settlementIds: string[] }

Matching is exact by default. tolerancePercent allows a bounded amount difference for that call. Entries with no matching candidate within tolerance are reported in exceptions and left unsettled.

`rollbackWorkflow`

Rolls back a committed or executing workflow using compensating transactions (the saga pattern) — each executed step is reversed in reverse order.

rollbackWorkflow(
    workflowPlanId: string,   // WorkflowPlan UUID to roll back
    reason: string,           // human-readable reason, recorded in the audit log
    agentId: string,
    sessionId: string,
) → { rollbackId: string, compensatedSteps: CompensatedStepItem[], status: string }

Each CompensatedStepItem includes stepOrder, description, and compensatingTransactionId where applicable.

rollbackWorkflow requires the separate AGENTS_ROLLBACK scope — it is never granted implicitly by AGENTS_EXECUTE. Compensating transactions bypass PolicyGuard by design, since a rollback is a corrective action rather than a new agent-initiated debit. Grant AGENTS_ROLLBACK only to admin-tier keys or agents whose role is specifically to reverse workflows.

`getAgentAuditLog`

Retrieves HMAC-signed audit events for agent actions, filterable by session and time range.

getAgentAuditLog(
    sessionId?: string,
    from?: string,
    to?: string,
    limit?: number,   // 1–200, default 50
) → { auditEvents: AuditEventItem[], total: number }

Each AuditEventItem includes id, workflowPlanId, agentId, sessionId, eventType, intentPayload, status, occurredAt, completedAt, and hmacSignature. Every mutating tool call writes a PENDING audit event before execution and a COMPLETED or FAILED event after — the audit log is append-only, and each event’s hmacSignature can be independently re-verified against your tenant’s audit HMAC secret.

Connect Claude Desktop

Expose your Idem instance

If you’re self-hosting locally, tunnel your instance so Claude Desktop can reach it (for example with ngrok http 8081). Skip this step if you’re on the managed cloud tier.

Create an agent-scoped API key

Using an ADMIN-scoped key, create a key carrying AGENTS_EXECUTE (and any other scopes the agent needs):

curl -X POST https://api.your-domain.com/api/v1/api-keys \
  -H "Authorization: Bearer $IDEM_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scopes":["AGENTS_EXECUTE","ACCOUNTS_READ"]}'

Copy the rawKey value from the response — it’s shown exactly once. See Scopes for the full reference.

Configure Claude Desktop

Add an entry to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/) using mcp-remote:

{
  "mcpServers": {
    "idem": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-idem-instance/sse"],
      "env": {
        "MCP_HEADER_X_API_KEY": "sk_agent_..."
      }
    }
  }
}

Restart Claude Desktop

The seven Idem tools appear in Claude’s tool list, scoped to whatever the key you configured is authorized to do.

Connect Claude Code

claude mcp add idem -- npx -y mcp-remote https://your-idem-instance/sse --header "X-API-Key: sk_agent_..."

Self-hosting: multi-replica deployments

If you self-host Idem across multiple replicas, configure sticky sessions at your load balancer so that a given MCP session’s GET /sse and subsequent POST /mcp/messages calls reach the same instance. Session state is held in-process per replica, not shared across a cluster.

Get Started

Core Concepts

Guides

Connect AI Agents to Idem via the MCP Server

How a tool call flows through Idem

Connect over SSE

Required scopes

Tools

`postTransaction`

`getBalance`

`listEntries`

`describeAccount`

`reconcileBatch`

`rollbackWorkflow`

`getAgentAuditLog`

Connect Claude Desktop

Connect Claude Code

Self-hosting: multi-replica deployments

​How a tool call flows through Idem

​Connect over SSE

​Required scopes

​Tools

​postTransaction

​getBalance

​listEntries

​describeAccount

​reconcileBatch

​rollbackWorkflow

​getAgentAuditLog

​Connect Claude Desktop

​Connect Claude Code

​Self-hosting: multi-replica deployments

How a tool call flows through Idem

Connect over SSE

Required scopes

Tools

`postTransaction`

`getBalance`

`listEntries`

`describeAccount`

`reconcileBatch`

`rollbackWorkflow`

`getAgentAuditLog`

Connect Claude Desktop

Connect Claude Code

Self-hosting: multi-replica deployments