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

Shell

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.
`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:

The agent calls ask with the question and options.
If you answer within wait_seconds, the tool returns your answer right away.
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.