# MCP for Claude Code, Codex and Cursor

The Cestra MCP server gives a coding agent tools to message you, ask you questions with buttons, show progress, and send or receive files. It runs locally over stdio and talks to `api.cestra.ai` with your agent's key. It needs Node 18 or newer.

## Install

### Claude Code

```sh
claude mcp add cestra --env CESTRA_KEY=cs_live_... -- npx -y https://docs.cestra.ai/dl/cestra-mcp.tgz
```

Add `--scope user` to make it available in every project. Check it with `claude mcp list`.

### Codex

Add this to `~/.codex/config.toml`:

```toml
[mcp_servers.cestra]
command = "npx"
args = ["-y", "https://docs.cestra.ai/dl/cestra-mcp.tgz"]
env = { CESTRA_KEY = "cs_live_..." }
```

### Cursor

Add this to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in a project:

```json
{
  "mcpServers": {
    "cestra": {
      "command": "npx",
      "args": ["-y", "https://docs.cestra.ai/dl/cestra-mcp.tgz"],
      "env": { "CESTRA_KEY": "cs_live_..." }
    }
  }
}
```

### Other MCP clients

Any client that launches stdio servers works. The command is `npx -y https://docs.cestra.ai/dl/cestra-mcp.tgz`, with `CESTRA_KEY` in the environment. Set `CESTRA_URL` only if you run your own Cestra server.

## Tools

| Tool | What it does |
| --- | --- |
| `send_message` | Posts a Markdown message to your thread. |
| `notify` | Posts a one-line notice with a tone: `info`, `success`, `warning` or `error`. |
| `ask` | Asks a question with up to 4 buttons and/or free text. It waits up to `wait_seconds` (default 120, max 600) for an answer. If nobody answers in time, it returns `pending` with an `ask_id`. |
| `check_replies` | Returns new messages, answers to earlier asks, form submissions and Stop requests since the last check, and acknowledges them. Pass `ask_id` to check one ask. `wait_seconds` (max 60) waits for news. |
| `start_job` | Starts a progress card with a title and optional steps. Returns the job id. |
| `update_job` | Sets percent, step status, title, or finishes the job (`done` or `failed` with an error). |
| `send_artifact` | Sends a table, chart, Markdown doc, form or HTML page. Reusing a `key` makes a new version. See [Artifacts](/artifacts). |
| `send_file` | Uploads a local file (≤ 50 MB) to the thread. |
| `get_file` | Downloads a file you sent to the agent and saves it locally. |

## How asks work over MCP

MCP tool calls can't block forever, so `ask` waits a bounded time:

1. The agent calls `ask` with the question and options.
2. If you answer within `wait_seconds`, the tool returns your answer right away.
3. If not, it returns `status: pending` and an id. The agent can keep working and call `check_replies` later. Your answer will be waiting there, even hours later.

Asks you create with `expires_in` expire on their own. After that, `check_replies` reports them as expired.

## Prompts that work well

```text
When you finish, send me a summary on Cestra with send_message.
```

```text
Before running migrations, use the Cestra ask tool with Approve / Cancel and wait up to 10 minutes.
```

```text
Every few minutes, call check_replies in case I sent new instructions.
```

## Troubleshooting

- **"Missing, invalid or revoked API key"**: the key is wrong or revoked. Create a new one under **Developer**.
- **The tools don't show up**: restart the client after adding the server, and check that `npx` is on the `PATH` the client uses.
- **Rate limited**: one key gets 60 requests per minute. The server retries after the `Retry-After` delay on its own.