> ## Documentation Index
> Fetch the complete documentation index at: https://developers.clara.team/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Quickstart

> Connect Claude Desktop, Claude Code, or any MCP-compatible tool to Clara in minutes.

## Before You Start

You need a Clara MCP token. If you don't have one yet, see [Clara MCP — Introduction](/mcp/introduction#how-to-get-a-token) 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:

```bash theme={null}
npx
```

If you see `Entering npm script environment`, you're ready. Skip to Step 2.

To install:

```bash theme={null}
brew install node
```

Or download the installer from [nodejs.org](https://nodejs.org).

**Windows** — check if Node.js is installed:

```bash theme={null}
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](https://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.

<Tabs>
  <Tab title="Mexico">
    ```json theme={null}
    {
      "mcpServers": {
        "clara-mcp": {
          "command": "npx",
          "args": [
            "-y",
            "supergateway",
            "--streamableHttp",
            "https://api.clara.team/mcp",
            "--header",
            "clara-mcp-token: YOUR_TOKEN_HERE"
          ]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Brazil">
    ```json theme={null}
    {
      "mcpServers": {
        "clara-mcp": {
          "command": "npx",
          "args": [
            "-y",
            "supergateway",
            "--streamableHttp",
            "https://api-prod.br.clara.com/mcp",
            "--header",
            "clara-mcp-token: YOUR_TOKEN_HERE"
          ]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Colombia">
    ```json theme={null}
    {
      "mcpServers": {
        "clara-mcp": {
          "command": "npx",
          "args": [
            "-y",
            "supergateway",
            "--streamableHttp",
            "https://api-gw-co-prod.clara.com/mcp",
            "--header",
            "clara-mcp-token: YOUR_TOKEN_HERE"
          ]
        }
      }
    }
    ```
  </Tab>
</Tabs>

Replace `YOUR_TOKEN_HERE` with your token. Keep everything else exactly as shown.

<Warning>
  This file contains your token. Do not share it or commit it to any version control system.
</Warning>

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

<Tabs>
  <Tab title="Mexico">
    ```bash theme={null}
    claude mcp add clara-mcp \
      --transport http \
      --url https://api.clara.team/mcp \
      --header "clara-mcp-token: YOUR_TOKEN_HERE"
    ```
  </Tab>

  <Tab title="Brazil">
    ```bash theme={null}
    claude mcp add clara-mcp \
      --transport http \
      --url https://api-prod.br.clara.com/mcp \
      --header "clara-mcp-token: YOUR_TOKEN_HERE"
    ```
  </Tab>

  <Tab title="Colombia">
    ```bash theme={null}
    claude mcp add clara-mcp \
      --transport http \
      --url https://api-gw-co-prod.clara.com/mcp \
      --header "clara-mcp-token: YOUR_TOKEN_HERE"
    ```
  </Tab>
</Tabs>

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](#server-urls-by-country) |
| 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.