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

# MCP server

> Run Cralo as a local Model Context Protocol server for MCP-native hosts.

Hosts that speak Model Context Protocol can talk to Cralo directly instead of shelling out to the CLI for every call. `cralo mcp serve` starts a local stdio MCP server backed by the same authenticated API client as the CLI.

## Setup

Authenticate first, then configure your host:

```bash theme={null}
cralo auth login
cralo integrations configure <host>
```

`<host>` is one of `claude-code`, `claude-desktop`, or `cursor`. For `claude-desktop` and `cursor`, the command prints the configuration by default; pass `--write` to merge it into the host's config file directly, and `--force` to overwrite an existing `cralo` entry. For `claude-code`, it prints a `claude mcp add` one-liner to run yourself.

### Claude Code

```bash theme={null}
cralo integrations configure claude-code
```

Prints the command to register the server directly with the Claude Code CLI:

```bash theme={null}
claude mcp add cralo -- cralo mcp serve
```

### Claude Desktop

```bash theme={null}
cralo integrations configure claude-desktop
# or write directly:
cralo integrations configure claude-desktop --write
```

Prints the config path (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows, `~/.config/Claude/claude_desktop_config.json` elsewhere) and the JSON block to merge into it:

```json theme={null}
{
  "mcpServers": {
    "cralo": {
      "command": "cralo",
      "args": ["mcp", "serve"]
    }
  }
}
```

`--write` merges this into the existing file without disturbing other configured servers. If a `cralo` entry already exists with different content, it refuses to overwrite unless `--force` is passed.

### Cursor

```bash theme={null}
cralo integrations configure cursor
# or write directly:
cralo integrations configure cursor --write
```

Prints the config path (`~/.cursor/mcp.json`) and the same `mcpServers.cralo` JSON block shown above.

## Meta-tools

`cralo mcp serve` exposes a small, fixed set of meta-tools rather than one MCP tool per catalog entry, so newly published tools are usable immediately without a host restart or a new MCP tool definition.

| Tool                         | Cost          | Purpose                                                               |
| ---------------------------- | ------------- | --------------------------------------------------------------------- |
| `opentooler_list_tools`      | Free          | List available tools (names and summaries only).                      |
| `opentooler_search_tools`    | Free          | Search tools by query; empty query lists tools.                       |
| `opentooler_describe_tool`   | Free          | Full schema, price, and documentation for one tool.                   |
| `opentooler_call_tool`       | Costs credits | Execute a tool with an automatic quote-based price guard.             |
| `opentooler_get_invocation`  | Free          | Get the current state or final result of an asynchronous invocation.  |
| `opentooler_wait_invocation` | Free          | Wait (bounded, cancellable) for an asynchronous invocation to finish. |
| `opentooler_get_balance`     | Free          | Get prepaid credit balance.                                           |

Agents should describe a tool before calling it (the same discipline as the CLI's `tools describe` before `tools call`). `opentooler_call_tool` applies a quote-based price guard automatically and accepts an optional `max_price_microusd` cap.

The `opentooler_*` MCP tool names are stable protocol identifiers and remain unchanged so existing host prompts and automations continue to work.

## Authentication

The MCP server uses the same credential as the CLI: the device-flow key stored after `cralo auth login`, or `CRALO_API_KEY` for headless hosts that can't complete an interactive login. If no credential is available when a tool is called, every meta-tool returns an `AUTH_REQUIRED` error asking the human to run `cralo auth login` in a terminal. The MCP server never prompts for login itself.