Add an MCP client

Connect Claude Code, Cursor, Codex or any other MCP client to your Executor endpoint, on hosted, self-host or a local server with an API key.

The dashboard’s Connect an agent page shows these commands with your own endpoint already filled in. Open it at /org/<your-organization>/connect on hosted and self-host, or Connect in the local dashboard.

The endpoint is your origin plus /mcp:

Most clients load MCP servers only at startup. After you add Executor, restart the client or open a new session before its tools appear.

Claude Code

Claude Code has its own command. --scope user adds Executor for every project.

claude mcp add --transport http --scope user executor 'https://v2.executor.sh/mcp'

Cursor, Codex and other clients

Use the installer. It detects the client and writes its configuration for you.

npx add-mcp 'https://v2.executor.sh/mcp' --transport http --name executor

{
  "mcpServers": {
    "executor": {
      "type": "http",
      "url": "https://v2.executor.sh/mcp"
    }
  }
}

If your client does not accept the installer, merge the configuration above into its MCP file by hand.

The same entry works for Cursor and for Codex. Both read a mcpServers map, and Executor needs nothing beyond a streamable HTTP URL. Sign-in happens in your browser the first time the client connects.

Connecting to a local server

A local server has no browser sign-in. It authenticates with the API key you configured as EXECUTOR_API_KEY, sent as a bearer token:

npx add-mcp 'http://127.0.0.1:4312/mcp' --transport http --name executor \
  --header 'Authorization: Bearer <key>'

{
  "mcpServers": {
    "executor": {
      "type": "http",
      "url": "http://127.0.0.1:4312/mcp",
      "headers": {
        "Authorization": "Bearer <key>"
      }
    }
  }
}

The local Connect page shows this with your real key. Keep the local server running while the client is connected.

Choosing where approvals appear

By default the agent relays an approval request to you and answers on your behalf with resume. To answer in your browser instead, add the mode to the URL before you connect:

claude mcp add --transport http --scope user executor 'https://v2.executor.sh/mcp?elicitation_mode=browser'

The mode is fixed when the connection is approved. To change it, connect again with the new URL. See The MCP endpoint for what each mode does.

Check that it worked

Ask the agent to run this:

return await tools.search({ query: "Executor" });

It should return callable paths for the Executor app itself. If the tool list is empty, the client has not reconnected since you added the server.