MCP Quickstart

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`

All servers use the same authentication method: a custom header 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:

npx

If you see Entering npm script environment, you’re ready. Skip to Step 2. To install:

brew install node

Or download the installer from nodejs.org. Windows — check if Node.js is installed:

node --version

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.

Mexico
Brazil
Colombia

{
  "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"
      ]
    }
  }
}

Replace 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:

Mexico
Brazil
Colombia

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"

Replace YOUR_TOKEN_HERE with your token. Clara MCP will be available in any Claude Code session.

Option C — Other MCP-Compatible Tools (ChatGPT, Gemini, etc.)

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.

Overview

Conventions

Guides

Resources

API Reference

MCP

VCN

Before You Start

Server URLs by Country

Option A — Claude Desktop (Recommended)

Step 1 — Install Node.js

Step 2 — Edit the Claude Desktop Config File

Step 3 — Restart Claude Desktop

Step 4 — Test It

Option B — Claude Code (CLI)

Option C — Other MCP-Compatible Tools (ChatGPT, Gemini, etc.)

Verify Your Connection

Troubleshooting

Token Management

​Before You Start

​Server URLs by Country

​Option A — Claude Desktop (Recommended)

​Step 1 — Install Node.js

​Step 2 — Edit the Claude Desktop Config File

​Step 3 — Restart Claude Desktop

​Step 4 — Test It

​Option B — Claude Code (CLI)

​Option C — Other MCP-Compatible Tools (ChatGPT, Gemini, etc.)

​Verify Your Connection

​Troubleshooting

​Token Management

Before You Start

Server URLs by Country

Option A — Claude Desktop (Recommended)

Step 1 — Install Node.js

Step 2 — Edit the Claude Desktop Config File

Step 3 — Restart Claude Desktop

Step 4 — Test It

Option B — Claude Code (CLI)

Option C — Other MCP-Compatible Tools (ChatGPT, Gemini, etc.)

Verify Your Connection

Troubleshooting

Token Management