Before You Start
You need a Clara MCP token. If you don’t have one yet, see Clara MCP — Introduction to request access.
Server URLs by Country
Each Clara market has its own MCP server URL. Use the one that matches your Clara account:
| Country | MCP Server URL |
|---|
| Mexico | https://api.clara.team/mcp |
| Brazil | https://api-prod.br.clara.com/mcp |
| Colombia | https://api-gw-co-prod.clara.com/mcp |
clara-mcp-token: <your_token>.
Option A — Claude Desktop (Recommended)
Claude Desktop is the easiest way to use Clara MCP. It runs on Mac or Windows.
Step 1 — Install Node.js
Claude Desktop uses a small bridge tool called supergateway to connect to Clara. This requires Node.js.
Mac — check if Node.js is installed:
If you see Entering npm script environment, you’re ready. Skip to Step 2.
To install:
Or download the installer from nodejs.org.
Windows — check if Node.js is installed:
If you see a version number (e.g., v20.x.x), skip to Step 2. Otherwise, download the .msi installer from nodejs.org and run it.
Step 2 — Edit the Claude Desktop Config File
Open this file on your computer:
- Mac:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
Add the following block inside the mcpServers object. If the file is empty or new, use the full structure below.
{
"mcpServers": {
"clara-mcp": {
"command": "npx",
"args": [
"-y",
"supergateway",
"--streamableHttp",
"https://api.clara.team/mcp",
"--header",
"clara-mcp-token: YOUR_TOKEN_HERE"
]
}
}
}
{
"mcpServers": {
"clara-mcp": {
"command": "npx",
"args": [
"-y",
"supergateway",
"--streamableHttp",
"https://api-prod.br.clara.com/mcp",
"--header",
"clara-mcp-token: YOUR_TOKEN_HERE"
]
}
}
}
{
"mcpServers": {
"clara-mcp": {
"command": "npx",
"args": [
"-y",
"supergateway",
"--streamableHttp",
"https://api-gw-co-prod.clara.com/mcp",
"--header",
"clara-mcp-token: YOUR_TOKEN_HERE"
]
}
}
}
YOUR_TOKEN_HERE with your token. Keep everything else exactly as shown.
This file contains your token. Do not share it or commit it to any version control system.
Step 3 — Restart Claude Desktop
Fully quit Claude Desktop (use File → Quit or Cmd+Q, not just close the window) and reopen it. When it opens, you will see clara-mcp listed in Claude’s available tools.
Step 4 — Test It
Ask Claude something like:
- “List my Clara cards”
- “Show my last 10 transactions”
- “Lock the card ending in 3540”
Claude will connect to Clara in real time and respond.
Option B — Claude Code (CLI)
If you use Claude Code in the terminal, add Clara MCP as an HTTP server:
claude mcp add clara-mcp \
--transport http \
--url https://api.clara.team/mcp \
--header "clara-mcp-token: YOUR_TOKEN_HERE"
claude mcp add clara-mcp \
--transport http \
--url https://api-prod.br.clara.com/mcp \
--header "clara-mcp-token: YOUR_TOKEN_HERE"
claude mcp add clara-mcp \
--transport http \
--url https://api-gw-co-prod.clara.com/mcp \
--header "clara-mcp-token: YOUR_TOKEN_HERE"
YOUR_TOKEN_HERE with your token. Clara MCP will be available in any Claude Code session.
Clara MCP uses the standard MCP protocol, so it works with any compatible AI tool. The exact configuration steps vary by tool — consult your tool’s documentation for how to add a custom MCP server.
When prompted, use these values:
| Field | Value |
|---|
| Server URL | See country table above |
| Authentication | Custom header |
| Header name | clara-mcp-token |
| Header value | Your token |
| Transport | Streamable HTTP |
Verify Your Connection
Once configured in any tool, test by asking:
“List my Clara cards”
If you see a list of cards from your company account, you are connected correctly.
Troubleshooting
“No tools found” or Clara MCP doesn’t appear
- Make sure you fully restarted the AI tool after editing the config (quit and reopen, not just refresh).
- Check the config file for typos — JSON is sensitive to missing commas and quotes.
- Confirm that
npx is available in your terminal (Claude Desktop only).
“Unauthorized” or 401 error
- Your token may be incorrect or expired. Contact your Clara Agent or Customer Happiness to verify.
- Make sure the header name is exactly
clara-mcp-token (lowercase, with hyphens).
“Connection refused” or server unreachable
- Check your internet connection.
- The Clara MCP server may be temporarily unavailable — try again in a few minutes.
Lock/unlock returns a simple “Ok” message
- This is a known Beta limitation. The operation executed correctly even if the response looks plain. The card was locked/unlocked successfully.
Transaction count shows 0
- Known Beta issue with the summary counter. Actual transactions are returned correctly in the list.
Token Management
- Your token is shown only once when issued. Store it in a password manager.
- To generate or revoke your token: go to Settings → Integrations → Clara MCP inside the Clara platform. Revocation takes effect immediately across all connected tools.
- After revoking, generate a new token from the same screen, update it in your config file, and restart your AI tool.
