# Connect MCP clients

> Wire Cursor, Claude Code, OpenCode, and other MCP clients via stdio (`executor mcp`) or streamable HTTP, including `add-mcp` setup and client restart requirements.

- Repository: RhysSullivan/executor
- GitHub: https://github.com/RhysSullivan/executor
- Human docs: https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052
- Complete Markdown: https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/llms-full.txt

## Source Files

- `apps/docs/local/cli.mdx`
- `apps/docs/mcp-proxy.mdx`
- `apps/cli/src/main.ts`
- `packages/hosts/mcp/src/tool-server.ts`
- `packages/core/api/src/server/mcp-build.ts`
- `apps/local/package.json`

---

---
title: "Connect MCP clients"
description: "Wire Cursor, Claude Code, OpenCode, and other MCP clients via stdio (`executor mcp`) or streamable HTTP, including `add-mcp` setup and client restart requirements."
---

Executor exposes one MCP endpoint that fronts your full tool catalog. Clients connect over **streamable HTTP** at `/mcp` on a running Executor server, or over **stdio** by launching `executor mcp` as a subprocess. The web UI **Connect an agent** card and `npx add-mcp` generate copy-paste setup for Cursor, Claude Code, OpenCode, and other MCP clients.

## Prerequisites

<Steps>
  <Step title="Install and start Executor">

Run the durable local service (or use a hosted deployment):

```bash
executor install
executor daemon status
```

For a throwaway foreground runtime instead, run `executor web --foreground`.

  </Step>
  <Step title="Confirm the MCP surface is reachable">

Local and self-hosted runtimes serve streamable HTTP at `<origin>/mcp`. Cloud runtimes use `<origin>/<org-slug>/mcp`. The **Connect an agent** card on the Integrations page prints the exact URL for your deployment.

An unauthenticated `POST` to the MCP URL should return **401** (auth challenge), not **404**. A 404 usually means the path or org segment is wrong.

  </Step>
</Steps>

## Choose a transport

| | Remote HTTP | Standard I/O (stdio) |
| --- | --- | --- |
| Client config | URL to `<origin>/mcp` | Command: `executor mcp` |
| Requires running daemon | Yes (`executor install` or `executor daemon run`) | No; CLI starts a foreground local server |
| Auth | Bearer token (local) or OAuth (cloud/self-host) | Built into the spawned process |
| Approval flow | `browser`, `model`, or `native` via `?elicitation_mode=` | `model` (default) or `browser` via `--elicitation-mode` |
| Desktop app | Supported (HTTP only) | Not shown; desktop routes through the sidecar over HTTP |

<Info>
After you add or change an MCP server entry, most clients only load servers at startup. Restart the client or open a new chat session before expecting `execute` and `resume` tools to appear.
</Info>

## Connect with `add-mcp`

`npx add-mcp` detects the installed MCP client and writes its config. Use the command from the **Connect an agent** card when possible; it already includes your origin, org slug (cloud), auth header (when needed), and elicitation mode.

<Tabs>
  <Tab title="Remote HTTP">

```bash
npx add-mcp http://127.0.0.1:4789/mcp --transport http --name executor
```

When the web UI has an active bearer session, the generated command may append an auth header:

```bash
npx add-mcp http://127.0.0.1:4789/mcp --transport http --name executor --header 'Authorization: Bearer <token>'
```

On Executor Cloud, the URL is org-scoped:

```bash
npx add-mcp https://executor.example/acme-corp/mcp --transport http --name executor
```

  </Tab>
  <Tab title="Standard I/O">

Requires the published `executor` CLI on your `PATH`:

```bash
npx add-mcp "executor mcp" --name executor
```

Pin a workspace scope (directory containing `executor.jsonc`):

```bash
npx add-mcp "executor mcp --scope /path/to/workspace" --name executor
```

Browser approval over stdio:

```bash
npx add-mcp "executor mcp --elicitation-mode browser" --name executor
```

  </Tab>
</Tabs>

<Warning>
Restart your MCP client after running `add-mcp`. Until the client reloads its server list, Executor tools will not be available in the session.
</Warning>

## Use the Connect card

The **Connect an agent** card on the Integrations page is the canonical source for install commands:

- **Remote HTTP** is the default tab. It targets streamable HTTP at your server's `/mcp` path (or `/<org-slug>/mcp` on cloud).
- **Standard I/O** appears on local runtimes where the `executor` CLI is on `PATH`. The desktop app shows HTTP only because it does not ship a global `executor` binary.
- **Advanced → Resume approvals** sets how paused tool calls are handled (see [Elicitation modes](#elicitation-modes) below).

Executor Cloud also surfaces MCP setup on `/setup-mcp` during onboarding.

## Manual client configuration

If you prefer to edit config files directly, use the same transport and URL the Connect card would generate.

### Claude Code / Cursor (stdio)

```json
{
  "mcpServers": {
    "executor": {
      "command": "executor",
      "args": ["mcp"]
    }
  }
}
```

With scope and browser approval:

```json
{
  "mcpServers": {
    "executor": {
      "command": "executor",
      "args": ["mcp", "--scope", "/path/to/workspace", "--elicitation-mode", "browser"]
    }
  }
}
```

### OpenCode (remote HTTP)

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "executor": {
      "type": "remote",
      "url": "http://127.0.0.1:4789/mcp",
      "enabled": true
    }
  }
}
```

Replace the URL with your deployment's MCP endpoint. On cloud, use `https://<host>/<org-slug>/mcp`.

## MCP endpoint reference

:::endpoint POST /mcp
Streamable-HTTP MCP transport. Creates a session on the first `POST` without an `mcp-session-id` header; subsequent requests forward to the active session. Also accepts `GET`, `DELETE`, and `OPTIONS` (CORS preflight).
:::

Local runtimes gate `/mcp` with a bearer token (401 when missing). Cloud and self-hosted deployments authenticate through their OAuth layer (401 challenge with protected-resource metadata).

<ParamField body="mcp-session-id" type="string">
Session identifier returned by the transport. Required on follow-up requests after session creation.
</ParamField>

<ParamField body="elicitation_mode" type="string">
Query parameter on the MCP URL. One of `browser`, `model`, or `native`. Defaults to `model`. Legacy alias: `allow_model_resume=true` maps to `model`.
</ParamField>

### Default ports by runtime

| Runtime | Typical port | MCP path |
| --- | --- | --- |
| `executor install` (supervised daemon) | `4789` | `/mcp` |
| `executor daemon run` | `4788` | `/mcp` |
| Docker self-host | `17888` | `/mcp` |
| Executor Cloud | HTTPS default | `/<org-slug>/mcp` |

The CLI may pick another free port when the default is busy. Use `executor daemon status` or the Connect card for the live origin; do not hard-code a port unless you pin it yourself.

## `executor mcp` (stdio)

```bash
executor mcp [--scope <dir>] [--elicitation-mode browser|model]
```

<ParamField body="--scope" type="string">
Sets `EXECUTOR_SCOPE_DIR` to a workspace directory containing `executor.jsonc`.
</ParamField>

<ParamField body="--elicitation-mode" type="browser | model" default="model">
`model` exposes a `resume` tool the agent calls with accept/decline/cancel. `browser` returns an approval URL and waits for a browser decision before resuming.
</ParamField>

Stdio behavior:

- The CLI reroutes `stdout` logging to `stderr` so MCP JSON-RPC on stdout stays clean.
- It starts a foreground local HTTP server, publishes a local server manifest, connects an MCP server over `StdioServerTransport`, and tears down when the client closes stdin or sends `SIGINT`/`SIGTERM`.
- Stdio does not support `native` elicitation; use Remote HTTP with `?elicitation_mode=native` for that mode.

## Elicitation modes

Paused executions (auth or policy approval) behave differently per mode:

| Mode | Transport | Behavior |
| --- | --- | --- |
| `model` (default) | HTTP query or stdio default | Agent calls the `resume` MCP tool with `executionId`, `action`, and optional `content` |
| `browser` | HTTP query or stdio `--elicitation-mode` | `execute` returns an `approvalUrl`; user approves in the web UI; agent calls `resume` to wait for the decision |
| `native` | HTTP query only | Executor uses the client's native MCP elicitation capability during `execute` |

HTTP examples:

```
http://127.0.0.1:4789/mcp?elicitation_mode=browser
https://executor.example/acme-corp/mcp?elicitation_mode=native
```

## MCP tools exposed to clients

Every Executor MCP session registers:

| Tool | Always present | Purpose |
| --- | --- | --- |
| `execute` | Yes | Run TypeScript against the tool catalog (discover, call, handle pauses) |
| `resume` | When elicitation mode is not `native` | Continue a paused execution |

New integrations added in the web UI or CLI appear in the catalog automatically; you do not reconfigure the MCP client per integration.

## Verify the connection

<Steps>
  <Step title="Restart or reload the client">

Quit and reopen the MCP client, or start a new chat/agent session, so it reloads server definitions.

  </Step>
  <Step title="Confirm tools are listed">

In the client, check that `execute` (and `resume` when applicable) appear in the MCP tool list.

  </Step>
  <Step title="Probe from the CLI">

```bash
executor tools sources
executor tools search "list issues"
```

These commands auto-start the local daemon when needed.

  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Tools do not appear after add-mcp">

Most MCP clients load servers only at startup. Restart the client or open a new chat. If you edited config manually, confirm JSON syntax and that the transport (`http` URL vs `command`/`args`) matches your chosen mode.

  </Accordion>
  <Accordion title="HTTP 401 on /mcp">

Local HTTP requires a bearer token on every `/mcp` request. Copy the `--header 'Authorization: Bearer …'` flags from the Connect card, or read the token from `auth.json` under your `EXECUTOR_DATA_DIR`. Cloud and self-hosted endpoints expect OAuth; complete the client authorization flow when prompted.

  </Accordion>
  <Accordion title="HTTP 404 on the Connect card URL">

On self-host, the server serves bare `/mcp` but the card may print `/<org-id>/mcp` for parity with cloud routing. The self-host front-end strips the org segment; if you still see 404, confirm you are hitting the correct origin and that the daemon is running (`executor daemon status`).

  </Accordion>
  <Accordion title="stdio: executor not found">

Install the global CLI (`npm install -g executor`) or switch to Remote HTTP. On monorepo dev checkouts, the Connect card uses `bun run dev:cli mcp` instead of `executor mcp`.

  </Accordion>
  <Accordion title="Paused execution not found on resume">

Paused executions live in the session runtime and expire after a few minutes or when the host restarts. Re-run `execute` with the original code to obtain a fresh `executionId`.

  </Accordion>
</AccordionGroup>

## Related pages

<CardGroup>
  <Card title="MCP proxy" href="/mcp-proxy">
    How Executor fronts OpenAPI, GraphQL, and upstream MCP integrations behind one endpoint.
  </Card>
  <Card title="Add integrations" href="/add-integrations">
    Register sources so they appear in the MCP catalog after you connect a client.
  </Card>
  <Card title="CLI reference" href="/cli-reference">
    Full `executor mcp`, `daemon`, and `install` flags and behavior.
  </Card>
  <Card title="Hosted cloud" href="/hosted-cloud">
    Org-scoped MCP URLs and OAuth on Executor Cloud.
  </Card>
  <Card title="Troubleshooting" href="/troubleshooting">
    Daemon port conflicts, unreachable servers, and recovery commands.
  </Card>
</CardGroup>