Using Custodia MCP

Custodia MCP is a remote Model Context Protocol (MCP) server. It lets AI clients — such as Cursor, Claude Code, and other MCP-compatible tools — call Custodia on your behalf: expenses, people, budgets, spend permissions, receipts, and more. Actions run as the signed-in user, within that user’s permissions.

This guide covers client setup for sandbox.

On this page

• Overview
• Environments
• What You Need
• Cursor Setup
  • Step 1: Configure ~/.cursor/mcp.json
  • Step 2: Connect and Sign In
  • Step 3: Use It
• Claude Code Setup
  • Step 1: Add the Server
  • Step 2: Authenticate
  • Step 3: Use It
• Available Tools
• Verify the Host (Optional)
• Troubleshooting
• Security Notes
• Related Articles

Overview

Custodia MCP exposes a curated set of Custodia tools to AI assistants. After you connect and sign in, you can ask questions in natural language — for example, “What did I spend last month?” or “List my budgets.” The assistant calls MCP tools when relevant; you only see tools allowed for your user and your organization’s AI configuration.

Transport: Streamable HTTP at POST and GET /mcp. Unauthenticated requests return 401 with a WWW-Authenticate header pointing at OAuth protected-resource metadata.

Environments

Contact Custodia for staging and production URLs when those hosts are enabled for your tenant.

What You Need

1. A Custodia user on the target environment (for example, sandbox).
2. An OAuth client ID for MCP — email support@custodia.ai to request one. Use this value as CLIENT_ID (Cursor) or clientId (Claude Code) in the setup steps below.

The client ID is not a secret — it identifies your MCP app registration and selects which tool catalogue (agent type) is available. What you can actually call is further limited by the signed-in user’s permissions. MCP IDE clients use public PKCE and do not have a client secret.

Cursor Setup

Step 1: Configure ~/.cursor/mcp.json

Use the provisioned client ID and scope. Cursor discovers the authorization server from the MCP host:

{
  "mcpServers": {
    "custodia-sandbox": {
      "url": "https://mcp.sandbox.custodia-tech.com/mcp",
      "auth": {
        "CLIENT_ID": "YOUR_OAUTH_CLIENT_ID",
        "scopes": ["mcp:execute"]
      }
    }
  }
}

Optional: store the client ID in an environment variable if your Cursor build supports ${env:...}:

"CLIENT_ID": "${env:CUSTODIA_MCP_OAUTH_CLIENT_ID}"

Do not add a CLIENT_SECRET — MCP IDE clients are public PKCE clients.

Step 2: Connect and Sign In

1. Open Cursor Settings → Tools & MCP.
2. Find custodia-sandbox (or the name you chose).
3. Click Connect or Needs authentication.
4. Complete browser sign-in on the Custodia sandbox host.
5. Confirm the server shows as connected and tools are listed.

If Connect does nothing, click the Needs authentication label, or check Output → MCP for the authorize URL and open it manually.

Step 3: Use It

In Agent chat, ask Custodia-backed questions naturally. Examples:

• “What did I spend last month?”
• “Find Sarah’s user id, then list her expenses for July.”
• “List my budgets.”

Tools are filtered by your user permissions and the agent type bound to the OAuth client (typically cursor-mcp).

Claude Code Setup

Step 1: Add the Server

CLI (recommended):

claude mcp add --transport http custodia-sandbox \
  https://mcp.sandbox.custodia-tech.com/mcp \
  --client-id YOUR_OAUTH_CLIENT_ID

If your registration requires a fixed callback port:

claude mcp add --transport http custodia-sandbox \
  https://mcp.sandbox.custodia-tech.com/mcp \
  --client-id YOUR_OAUTH_CLIENT_ID \
  --callback-port 8787

Ensure that exact redirect URI (http://localhost:8787/callback) is on the OAuth client’s redirectUris.

Or JSON in project .mcp.json or user config:

{
  "mcpServers": {
    "custodia-sandbox": {
      "type": "http",
      "url": "https://mcp.sandbox.custodia-tech.com/mcp",
      "oauth": {
        "clientId": "YOUR_OAUTH_CLIENT_ID",
        "callbackPort": 8787,
        "scopes": "mcp:execute"
      }
    }
  }
}

Important:

• type is required (http or alias streamable-http). A url without type is treated as a broken stdio server.
• No client secret for public clients.
• If discovery against the authorization server is flaky, Claude Code v2.1.64+ supports oauth.authServerMetadataUrl pointing at https://sandbox.custodia-tech.com/.well-known/oauth-authorization-server.

Step 2: Authenticate

In a Claude Code session, run:

/mcp

Select custodia-sandbox and complete the browser login. Tokens are stored by Claude Code and refreshed automatically.

Step 3: Use It

Same natural-language prompts as Cursor. Claude calls MCP tools when relevant.

Available Tools

MCP exposes a curated catalogue — not every Custodia API. The client ID determines the broad tool list for your agent type; your user permissions reduce that list to what you can actually use in a session. Admins configure agent scopes in Custodia AI Config.

Verify the Host (Optional)

These checks confirm the MCP endpoint and OAuth metadata are reachable.

Initialize request (expect 401):

curl -sS -D - -o /dev/null -X POST \
  "https://mcp.sandbox.custodia-tech.com/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

Expect 401 and a WWW-Authenticate header referencing /.well-known/oauth-protected-resource.

Protected resource metadata:

curl -sS "https://mcp.sandbox.custodia-tech.com/.well-known/oauth-protected-resource"

Authorization server metadata:

curl -sS "https://sandbox.custodia-tech.com/.well-known/oauth-authorization-server"

Troubleshooting

Security Notes

• The client ID is not a secret — it only selects which tool catalogue is available for that MCP registration. Access is enforced by the signed-in user’s permissions and short-lived OAuth tokens.
• MCP IDE clients use public PKCE with agentic-delegate tokens — short-lived delegate JWTs, not long-lived secrets.
• MCP acts on behalf of the signed-in user within Custodia ACLs — treat a connected IDE like a privileged session.
• If a laptop is lost or you suspect an active MCP session is compromised, revoke access from Custodia Connected Apps or disconnect the server in your IDE and sign in again.

Related Articles

• API Access Key Credentials Guide
• What is a Service User?
• API User Management

Questions or need staging/production URLs? Contact support@custodia.ai.