# Clatri MCP

URL: https://docs.clatri.com/en/mcp/

> Connect Clatri to Claude Desktop, Claude Code, Cursor, or Codex using the MCP protocol.

The **Clatri MCP** lets you connect your Clatri information to external AI clients like Claude Desktop, Cursor, Claude Code, or Codex. The external assistant reads and, if you authorize it, writes to your data — always within the permissions you grant to the token.

For the curious: MCP stands for **Model Context Protocol**, an open standard created by Anthropic. Any compatible client can connect to Clatri without us having to build a proprietary integration.

:::tip When to use the MCP?
If you already talk to Claude or Cursor all day and would like them to have access to your Clatri data without opening the app. For example: *"how much did I spend on restaurants this month?"* directly in Claude Desktop, no copy-paste.
:::

---

## How it works, in one picture

```mermaid
flowchart LR
    Client["🤖 Your AI client<br/>(Claude Desktop, Cursor, …)"]
    Token["🔑 MCP token<br/>(clt_mcp_…)"]
    API["⚙️ api.clatri.com/mcp"]
    Data["🗄️ Your Clatri data<br/>(with your permissions)"]

    Client -- "Authorization: Bearer" --> Token
    Token --> API
    API -- "validates + filters by entity and scope" --> Data
    Data -- "JSON" --> API
    API -- "MCP response" --> Client

    style Client fill:#3b82f6,stroke:#2563eb,color:#fff
    style Token fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style API fill:#6366f1,stroke:#4f46e5,color:#fff
    style Data fill:#10b981,stroke:#059669,color:#fff
```

Every time the AI client asks a question, it sends the token to the Clatri backend. The backend validates the token, checks which entities and permissions it has, runs the requested tool, and returns the response. **It never exposes your password, your app session, or impersonates you outside Clatri.**

---

## Requirements

<details>
<summary>You need an active Clatri subscription</summary>

The MCP is a premium feature. Without a subscription:

- **You can't create tokens** — the button returns an error asking you to renew.
- **If your subscription expires with active tokens**, those tokens stop working (they respond 402) until you reactivate. They're not deleted — they go back to working automatically when you renew.

This covers the cost of processing your requests with low latency and keeping the infrastructure secure.

<details>
<summary>You need an MCP-compatible client</summary>

The most popular ones:
- **Claude Desktop** (Mac, Windows) — graphical install
- **Claude Code** (CLI) — `claude mcp add`
- **Cursor** (IDE) — Settings → MCP
- **Codex CLI** (OpenAI) — `~/.codex/config.toml`

Other clients that also work: Continue, Cline, Zed, mcp-cli, any integration that speaks streamable HTTP MCP.

---

## Step 1 — Create your token

1. Open the Clatri app → **Settings** → **API tokens**.
2. Tap **+ New token**.
3. Give it a name you'll recognize (e.g. "Claude Desktop on my Mac").
4. Choose the permission level:
   - **Read only** — the client can query but doesn't modify anything.
   - **Read + Write** — can create and edit (expenses, episodes, notes, etc.).
   - **Full access** — also includes delete.
5. Tap **Create token**.

:::warning Copy it right away
The token is shown **only once**. If you lose it, we can't recover it — you have to revoke it and create a new one. Paste it immediately into your client or save it in your password manager.
:::

The token expires automatically after 6 months. You can revoke it manually anytime from the same screen.

---

## Step 2 — Connect it to your client

From the terminal:

```bash
claude mcp add clatri \
  --transport http \
  --scope user \
  https://api.clatri.com/mcp \
  --header "Authorization: Bearer clt_mcp_YOUR_TOKEN_HERE"
```

- `--scope user` registers it globally (available in every project). Use `--scope project` if you only want it in this repo (lives in `.mcp.json`).
- `--transport http` is required because the Clatri MCP is remote.

Verify it connected:

```bash
claude mcp list
```

You should see `clatri: connected ✓`. In your next Claude Code session, the `whoami`, `list_entities` and other tools will appear automatically.

This manual setup uses `mcp-remote` to connect Clatri's remote server through Claude Desktop's **local MCP servers** settings.

1. Install [Node.js LTS](https://nodejs.org/en/download), which includes npm and npx. They must be available on your system for this method. Check in a new terminal:

```text
node --version
npm --version
```

On Windows, use Command Prompt (`cmd`) and also run `where npx.cmd`. If you just installed Node.js, fully quit and reopen Claude so it receives the updated PATH.

2. Open **Claude Desktop → Settings → Desktop app → Developer → Edit Config** to edit `claude_desktop_config.json`:
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
3. Add `clatri` inside `mcpServers`. Preserve any existing `preferences` object: `mcpServers` belongs at the same top level, outside `preferences`. Keep your other servers too.

**Windows:**

```json
{
  "mcpServers": {
    "clatri": {
      "command": "npx.cmd",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.clatri.com/mcp",
        "--header",
        "Authorization:${CLATRI_AUTH_HEADER}"
      ],
      "env": {
        "CLATRI_AUTH_HEADER": "Bearer clt_mcp_YOUR_TOKEN_HERE"
      }
    }
  }
}
```

**macOS:** use the same block, replacing `"command": "npx.cmd"` with `"command": "npx"`.

Replace the example token with yours. Keep the space between `Bearer` and the token in the environment variable. Do not add spaces to `Authorization:${CLATRI_AUTH_HEADER}`: this avoids the [Windows argument issue documented by mcp-remote](https://github.com/punkpeye/mcp-remote#custom-headers).

4. Save the JSON and **fully quit Claude Desktop**. On Windows, check that it is no longer running in the system tray. Then reopen it.
5. Check that `clatri` is **Running** in Developer settings. Open a new chat and check **+ → Connectors** to make sure Clatri is available and enabled. You do not need a special Clatri section or chat.
6. Ask: **“Use Clatri MCP and list my entities.”** Claude should actually invoke the tool rather than answer from memory.

These instructions cover manual JSON setup. Desktop `.mcpb` extensions can use Claude's bundled Node.js runtime; they are a [different installation method](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop).

1. **Cursor → Settings → Cursor Settings → MCP** (or edit `~/.cursor/mcp.json` directly).
2. Click **+ Add new MCP server**.
3. Pick the **HTTP** transport and paste:
   - **Name:** `clatri`
   - **URL:** `https://api.clatri.com/mcp`
   - **Headers:** `Authorization: Bearer clt_mcp_YOUR_TOKEN_HERE`
4. Save. Cursor shows the connection status with a green dot if it connected OK.

Equivalent via file:

```json
{
  "mcpServers": {
    "clatri": {
      "url": "https://api.clatri.com/mcp",
      "headers": {
        "Authorization": "Bearer clt_mcp_YOUR_TOKEN_HERE"
      }
    }
  }
}
```

Edit `~/.codex/config.toml` and add:

```toml
[mcp_servers.clatri]
url = "https://api.clatri.com/mcp"
http_headers = { "Authorization" = "Bearer clt_mcp_YOUR_TOKEN_HERE" }
```

Recommended: instead of pasting the token directly, use an env var:

```toml
[mcp_servers.clatri]
url = "https://api.clatri.com/mcp"
bearer_token_env_var = "CLATRI_MCP_TOKEN"
```

and in your shell:

```bash
export CLATRI_MCP_TOKEN="clt_mcp_YOUR_TOKEN_HERE"
```

Restart Codex (ctrl+C and reopen).

---

## Step 3 — Check that it works

In your freshly configured client, type one of these:

```text
Who am I in Clatri and which entities do I have access to?
```

```text
List my Clatri entities.
```

If everything is OK, the client will use the `whoami` and `list_entities` tools and reply with your name, the available entities (Personal, Company, etc.) and the token's permissions.

---

## What you can ask it (examples)

Once connected, these prompts work in any client:

| Question | Tools it uses |
| --- | --- |
| *"How much did I spend on restaurants last month from my personal account?"* | `list_entities`, `read_income_statement` |
| *"Summarize my accounts and current balances."* | `list_entities`, `list_accounts`, `get_balance` |
| *"Log a $45 USD Uber expense for today on Gurwi LLC."* | `list_entities`, `create_expense` (requires write scope) |
| *"When is my next obligation due and how much is it?"* | `list_obligations` |
| *"What medications am I currently taking."* | `list_medications` |

:::tip For vague questions
If you don't know exactly which tool to use, just ask the client in natural language. Modern LLMs pick the right tools automatically.
:::

---

## Security

<details>
<summary>The token never grants access outside Clatri</summary>

Even if the token leaks:
- It only applies the scopes you granted (read / write / delete).
- It only reaches data inside Clatri — no access to your password, no email change, no 2FA reset.
- It can't create more tokens, revoke others, or touch your subscription.
- You can revoke it instantly from Settings → Connections → Clatri MCP.

Every operation is logged in the **audit log** (Settings → Connections → Clatri MCP → tap a token → view recent activity). If you see unusual usage, revoke it.

<details>
<summary>Restrict a token to specific entities</summary>

By default a token has access to the same entities as your account — own and shared. When you create or edit a token you can **select only the entities the AI client will see**. Useful for:

- A token for your accountant that only sees the company.
- A test token that only accesses a sandbox entity.
- An AI client on your personal computer that can't touch work data.

After creation you can change entities, permissions, and the name from Settings → Connections → Clatri MCP → tap the menu (`···`) → **Edit**. You don't have to generate a new token every time you tweak its scope.

<details>
<summary>The token expires after 6 months</summary>

For security. When it expires, you simply create a new one and replace it in the client. There's no way to extend the expiration — that's by design.

---

## Troubleshooting

<details>
<summary>The client says "401 unauthorized"</summary>

- The token expired → create a new one.
- You revoked it by mistake → create a new one.
- You copied it wrong (missing the `clt_mcp_` prefix or with an extra space) → verify the `Authorization: Bearer clt_mcp_...` header.

<details>
<summary>The client says "402 subscription_inactive"</summary>

Your Clatri subscription isn't active. Renew it in the app and try again — the same token keeps working.

<details>
<summary>The client says "403 scope_denied" or "entity_denied"</summary>

- **scope_denied**: the token doesn't have the required permission (e.g. it wants to write but you only gave it read). Create a new token with more scopes and replace.
- **entity_denied**: the client tried to touch an entity the token doesn't allow. If you want to broaden it, revoke and create a new token without entity restriction.

<details>
<summary>"Browser origins not allowed"</summary>

You're trying to talk to `/mcp` from a browser or web tab. Legitimate MCP clients are native processes (Claude Desktop, Claude Code CLI, Cursor desktop). This is anti DNS-rebinding protection — it's not a bug, it's by design.

<details>
<summary>The client doesn't detect the tools after installing</summary>

- Fully restart the client (not just minimize).
- Claude Code: run `claude mcp list` to see if it appears. If it says "failed", check the header format.
- Codex: run with `--verbose` or check logs in `~/.codex/log/`.

---

## Frequently asked questions

<details>
<summary>How many tokens can I create?</summary>

Up to 10 active tokens per user. If you reach the limit, revoke an old one before creating a new one.

<details>
<summary>Can I share a token with someone else?</summary>

Technically yes (it's just a string), but **not recommended**. If that person needs access to your Clatri, it's better to share the entity from Settings → Share entities and give them their own access with their account. Tokens are personal.

<details>
<summary>Do AI-client actions show up in my Clatri chat history?</summary>

After a task that changes data, the external agent is instructed to call `registrar_resumen_actividad`. This saves one **External activity · MCP** card in the entity chat, with a summary, expandable changes and local time. Read-only tasks do not create a card. Delivery depends on the client following the instruction; it is not an automatic session detector or a push notification. The card is the external agent’s report, not independent verification by Clatri.

<details>
<summary>What happens to my token when I rotate my Supabase API keys or JWT signing keys?</summary>

Nothing. The MCP token is independent from Supabase's internal auth system. Backend key rotations are transparent to MCP tokens.

<details>
<summary>Are there rate limits?</summary>

Yes, but conservative — designed for normal human usage via an AI client, not for mass automation. If you hit the limit, you'll see `429 rate_limited` in the audit log. If you need more volume, contact us.

## Personal context through MCP

`read_user_context` returns the active entity’s description, behavioral defaults, personality and preferences shared across channels. The client is instructed to read it at the start of a task; MCP does not automatically inject it into every external conversation. `buscar_memoria` retrieves relevant historical memories.

`edit_entity_context` and `remember_user_preference` can use an exact user quote from the external conversation when `source_message_id` is omitted. That evidence is labeled **client-reported**, not verified Clatri chat history. Chat-only preferences remain excluded from external context; use `channel_scope=all` only when the user authorizes sharing across channels.

Reconnect the MCP after updates so the client refreshes tools and instructions. Existing tokens remain valid within their permissions. The documentation link remains available after creating tokens in Flutter and web.

## Totals and usage when querying from Claude

For **“How much did I spend or earn this month/year?”**, request the **income statement** (`read_income_statement`). It uses the same accounting basis as **Earned and spent**: transfers between your own accounts and debt principal payments are not income or expenses. Use `read_cashflow_report` for money entering or leaving accounts.

`read_expenses` and `read_incomes` show movement details and a separate accounting total. The detail list can be limited; do not sum it to calculate the period total.

Example: “Use Clatri MCP to read my income statement from September 1 through September 30, 2026. Report income, expenses, and the tool used.”

These direct data queries do not run Clatri's conversational model. Adding “without spending Clatri tokens” does not change billing. Claude has its own usage, and MCP access requires an active Clatri subscription.

### “Server disconnected” on Windows

1. Check `node --version`, `npm --version`, and `where npx.cmd` in `cmd`.
2. Use `npx.cmd` and the environment-variable configuration above. If the executable cannot be found, use the full path returned by `where`, escaping backslashes as `\\` in JSON.
3. Fully quit and reopen Claude.
4. If it still fails, open **Developer → clatri → View logs**. “Server disconnected” alone cannot distinguish installation, authentication, and network errors. Hide tokens before sharing logs or screenshots; revoke and replace any exposed token.