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.

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.

Hostname placeholders

Use these placeholders consistently:

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.

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.

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:

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.

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:

[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:

[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.

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.

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:

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:

{
  "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.

Hermes Agent

For a dedicated walkthrough, see Quick Start: Hermes MCP.

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.

MCP_API_KEY=mcp_live_...

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.

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:

For generic header auth, use:

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.

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:

If the form exposes custom headers, use:

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.

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

Restart Cursor or reload the MCP server list after saving the file.

Header-capable clients

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

{
  "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.

{
  "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.