# MCP Client Configuration

Canonical page: https://www.kuudo.com/docs/mcp-client-configuration/

Use these examples to connect MCP clients and custom agents to your private MCP server.

Your MCP server hostname is private to your deployment. It comes from your cloud provider, belongs to your environment, and is not shared across customers. Replace every example host below with the private host shown in your dashboard.

```text
https://{your-private-mcp-host}/mcp
```

For example, your endpoint might look like a private application hostname from AWS, GCP, Azure, Cloudflare, or your internal DNS. Do not assume any public example hostname is your production host unless your dashboard explicitly shows it.

## Before you start

Create an API key from the dashboard **Keys** tab. Header-capable clients authenticate with an `Authorization` bearer header. Prefer injecting `MCP_API_KEY` from your local environment or secret manager instead of pasting keys into chat, screenshots, repositories, or shared config.

Claude custom connectors are different: they use the signed Claude connector URL from the same **Keys** tab.

| Client | Auth shape |
| --- | --- |
| Claude custom connector | Signed `/mcp/connect/{token}` URL |
| Claude Code | Bearer header from `MCP_API_KEY` |
| Codex | `codex mcp add` with bearer token environment variable |
| OpenClaw | `mcp.servers` entry with bearer header. See [OpenClaw MCP](/docs/quick-start/openclaw/). |
| Hermes Agent | `mcp_servers` entry with bearer header. See [Hermes MCP](/docs/quick-start/hermes/). |
| n8n | MCP Client Tool node with bearer, header, or OAuth2 auth. See [n8n MCP](/docs/quick-start/n8n/). |
| Activepieces | Run Agent > Agent Tools > Add MCP Server with Streamable HTTP and optional auth. See [Activepieces MCP](/docs/quick-start/activepieces/). |
| Cursor | Bearer header from `MCP_API_KEY` |
| Custom agent | Remote HTTP MCP endpoint plus bearer header |

## Hostname placeholders

Use these placeholders consistently:

| Placeholder | Meaning |
| --- | --- |
| `{your-private-mcp-host}` | The private MCP hostname assigned to your deployment by your cloud provider. |
| `{signed-token}` | The dashboard-generated token embedded in the Claude connector URL. |
| `MCP_API_KEY` | Your local environment variable or secret-manager value for bearer auth. |

Use the normal `/mcp` endpoint for bearer-auth clients. Reserve `/mcp/connect/{signed-token}` for Claude custom connectors.

## Claude custom connector

Copy the Claude connector URL from the dashboard, then add it in Claude through **Customize > Connectors > Add custom connector**. Name the connector something clear, such as `private-mcp`.

```text
https://{your-private-mcp-host}/mcp/connect/{signed-token}
```

Use the signed connector URL for this flow. The Claude custom connector UI does not accept a separate `Authorization` header.

## Claude Code

Set your key once, then add the remote HTTP MCP server from any Claude Code session.

```bash
export MCP_API_KEY="mcp_live_..."

claude mcp add --transport http private-mcp https://{your-private-mcp-host}/mcp \
  --header 'Authorization: Bearer ${MCP_API_KEY}'
```

Add `--scope project` to share the server through the repository's `.mcp.json`, or `--scope user` for your local Claude Code profile.

JSON form:

```bash
claude mcp add-json private-mcp '{
  "type": "http",
  "url": "https://{your-private-mcp-host}/mcp",
  "headers": {
    "Authorization": "Bearer ${MCP_API_KEY}"
  }
}'
```

## Codex

Set your key once, then add the remote HTTP MCP server with the Codex CLI. Codex shares MCP configuration between the CLI and IDE extension.

```bash
export MCP_API_KEY="mcp_live_..."

codex mcp add private-mcp \
  --url https://{your-private-mcp-host}/mcp \
  --bearer-token-env-var MCP_API_KEY
```

Config file form:

```toml
[mcp_servers.private-mcp]
url = "https://{your-private-mcp-host}/mcp"
bearer_token_env_var = "MCP_API_KEY"
```

Verify with `codex mcp list`. In the Codex TUI, run `/mcp` to see active servers for the current session. For trusted projects, you can scope configuration to the repository with `.codex/config.toml`.

Optional controls:

```toml
[mcp_servers.private-mcp]
url = "https://{your-private-mcp-host}/mcp"
bearer_token_env_var = "MCP_API_KEY"
enabled_tools = ["search", "fetch"]
disabled_tools = ["delete_record"]
default_tools_approval_mode = "prompt"
tool_timeout_sec = 60
```

If your server uses OAuth instead of bearer-token authentication, add the server first, then run `codex mcp login private-mcp`.

## OpenClaw

For a dedicated walkthrough, see [Quick Start: OpenClaw MCP](/docs/quick-start/openclaw/).

OpenClaw's MCP command has two different modes:

- `openclaw mcp serve` runs OpenClaw itself as a stdio MCP server for another client.
- `openclaw mcp set`, `list`, `show`, and `unset` manage OpenClaw-owned outbound MCP server definitions under `mcp.servers`.

Use the `set` path when you want an OpenClaw-managed runtime to know about your private MCP server. This saves the server definition in OpenClaw config; it does not start a live MCP session or prove the remote server is reachable.

Set your key in the environment OpenClaw uses, then register the private server with OpenClaw's `mcp.servers` config shape.

```bash
export MCP_API_KEY="mcp_live_..."

openclaw mcp set private-mcp '{"transport":"streamable-http","url":"https://{your-private-mcp-host}/mcp","headers":{"Authorization":"Bearer ${MCP_API_KEY}"}}'
```

Keep the single quotes around the JSON so OpenClaw stores the literal environment-variable reference.

Inspect the saved definition:

```bash
openclaw mcp list
openclaw mcp show private-mcp --json
```

OpenClaw supports stdio, SSE/HTTP, and streamable HTTP definitions. For a modern remote MCP endpoint, set `"transport": "streamable-http"`. If `transport` is omitted, OpenClaw treats a URL-based entry as SSE/HTTP.

If you set `MCP_API_KEY` after OpenClaw or a runtime adapter is already running, restart that process before expecting it to read the new environment variable. Runtime adapters decide which saved MCP definitions they consume and when they open a connection.

Manual config form:

```json
{
  "mcp": {
    "servers": {
      "private-mcp": {
        "transport": "streamable-http",
        "url": "https://{your-private-mcp-host}/mcp",
        "headers": {
          "Authorization": "Bearer ${MCP_API_KEY}"
        }
      }
    }
  }
}
```

For the official OpenClaw reference, see [OpenClaw `mcp`](https://docs.openclaw.ai/cli/mcp).

## Hermes Agent

For a dedicated walkthrough, see [Quick Start: Hermes MCP](/docs/quick-start/hermes/).

Store your key in `~/.hermes/.env` or the environment that launches Hermes, then add the private server under the top-level `mcp_servers` key in `~/.hermes/config.yaml`.

```dotenv
MCP_API_KEY=mcp_live_...
```

```yaml
mcp_servers:
  private-mcp:
    url: "https://{your-private-mcp-host}/mcp"
    headers:
      Authorization: "Bearer ${MCP_API_KEY}"
    enabled: true
    timeout: 120
    connect_timeout: 60
```

Hermes expands `${MCP_API_KEY}` from its local environment. If the variable is unset, the placeholder remains literal and authentication fails. Restart Hermes or run `/reload-mcp` after saving config changes. Hermes discovers tools at startup or reload time and prefixes them as `mcp_<server_name>_<tool_name>`.

## n8n

For a dedicated walkthrough, see [Quick Start: n8n MCP](/docs/quick-start/n8n/).

Use n8n's **MCP Client Tool** node when an n8n AI Agent workflow should call tools from your private MCP server. n8n also has an **MCP Server Trigger** node, but that is the opposite direction: it exposes n8n workflows to external agents.

In the MCP Client Tool node:

| n8n field | Value |
| --- | --- |
| SSE Endpoint | `https://{your-private-mcp-host}/mcp` |
| Authentication | Bearer, generic header, or OAuth2 |
| Tools to Include | `Selected` for narrow production workflows, or `All` while testing |

For generic header auth, use:

| Header | Value |
| --- | --- |
| `Authorization` | `Bearer <MCP_API_KEY>` |

Store the key in n8n credentials. Do not paste raw keys into workflow descriptions, sticky notes, or prompts.

## Activepieces

For a dedicated walkthrough, see [Quick Start: Activepieces MCP](/docs/quick-start/activepieces/).

Use the **Run Agent** step's **Agent Tools** area when an Activepieces agent should connect to your private MCP server. Click **Add** under Agent Tools, then choose the MCP option. This is separate from Activepieces' own MCP server feature, which exposes Activepieces tools to external MCP clients.

Current visible Add MCP Server fields:

| Field | Value |
| --- | --- |
| MCP Name | `private-mcp` |
| Server URL | `https://{your-private-mcp-host}/mcp` |
| Protocol | `Streamable HTTP` |
| Authentication Type | Bearer or header-based auth if available; otherwise the observed default is `None` |

If the form exposes custom headers, use:

```text
Authorization: Bearer ${MCP_API_KEY}
```

Use Activepieces credential or secret storage for the key if the form provides it. Do not paste raw live keys into labels, descriptions, prompts, or workflow notes.

## Cursor

For repository scope, save this as `.cursor/mcp.json`. For user scope, save it as `~/.cursor/mcp.json`.

```json
{
  "mcpServers": {
    "private-mcp": {
      "url": "https://{your-private-mcp-host}/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MCP_API_KEY}"
      }
    }
  }
}
```

Cursor expands `${env:MCP_API_KEY}` from its environment; the bare `${MCP_API_KEY}` form is not expanded. Restart Cursor or reload the MCP server list after saving the file. See the [Cursor quick start](/docs/quick-start/cursor/) for the full setup.

## Header-capable clients

Most MCP clients use an `mcpServers` object with a remote URL and request headers.

```json
{
  "mcpServers": {
    "private-mcp": {
      "url": "https://{your-private-mcp-host}/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MCP_API_KEY}"
      }
    }
  }
}
```

Check your client documentation for its exact environment-variable interpolation syntax. Some clients use `${MCP_API_KEY}`; others use `${env:MCP_API_KEY}`.

## Custom agent

If your agent owns its MCP client layer, store the endpoint and header in your agent configuration and inject the API key from a secret manager or environment variable.

```json
{
  "name": "private-mcp",
  "transport": "http",
  "url": "https://{your-private-mcp-host}/mcp",
  "headers": {
    "Authorization": "Bearer ${MCP_API_KEY}"
  },
  "capabilities": {
    "tools": true,
    "resources": true
  }
}
```

Use `https://{your-private-mcp-host}/mcp` for normal bearer auth. Reserve `https://{your-private-mcp-host}/mcp/connect/{signed-token}` for Claude custom connectors.

## Verify the connection

After adding the server, restart or reload the MCP client and ask it to list the available tools. If the server does not appear, check three things first:

1. The hostname matches the private host in your dashboard.
2. `MCP_API_KEY` is set in the environment that launches the client.
3. The client is using `/mcp` for bearer auth or `/mcp/connect/{signed-token}` for Claude custom connectors, not both.