MCP

HALO exposes a Model Context Protocol (MCP) server that allows external MCP clients — such as Claude Code, Codex, or your own custom agents — to interact with your HALO environment. This enables you to trigger agents, query knowledge, and use HALO's capabilities as tools in any MCP-compatible workflow.

Server details

Required headers

Creating an MCP token

1. In HALO Studio, go to Settings > Product Tokens.

2. Click + and give the token a descriptive name (e.g. Claude Code MCP).

3. Select type MCP and save.

4. Copy the generated token immediately — it is only shown once. Use it as the value for X-CM-PRODUCTTOKEN.

We recommend storing all three values (X-CM-PRODUCTTOKEN, CM-ACCOUNT-ID, CM-PROFILE-ID) as environment variables — e.g. HALO_MCP_TOKEN, HALO_ACCOUNT_ID, HALO_PROFILE_ID — rather than pasting them directly into config files, wherever your client supports it.

Connecting from Claude Code

claude mcp add --transport http halo https://api.cm.com/halo/core/mcp \
  --header "X-CM-PRODUCTTOKEN: <your-mcp-token>" \
  --header "CM-ACCOUNT-ID: <your-account-id>" \
  --header "CM-PROFILE-ID: <your-profile-id>"

To share the configuration with your team, add it to .mcp.json in your project root, referencing environment variables instead of hardcoded values:

{
  "mcpServers": {
    "halo": {
      "type": "http",
      "url": "https://api.cm.com/halo/core/mcp",
      "headers": {
        "X-CM-PRODUCTTOKEN": "${HALO_MCP_TOKEN}",
        "CM-ACCOUNT-ID": "${HALO_ACCOUNT_ID}",
        "CM-PROFILE-ID": "${HALO_PROFILE_ID}"
      }
    }
  }
}

Verify with claude mcp list — the server should show ✓ Connected.

Connecting from Claude Desktop (manual config)

Claude Desktop's Settings → Connectors screen doesn't support custom headers, so this only works by editing the config file directly:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\\Claude\\claude_desktop_config.json

Add the same mcpServers block shown above, then fully restart Claude Desktop.

Connecting from Codex CLI

Add to ~/.codex/config.toml (or .codex/config.toml for a project-scoped server):

[mcp_servers.halo]
url = "https://api.cm.com/halo/core/mcp"
env_http_headers = { "X-CM-PRODUCTTOKEN" = "HALO_MCP_TOKEN", "CM-ACCOUNT-ID" = "HALO_ACCOUNT_ID", "CM-PROFILE-ID" = "HALO_PROFILE_ID" }

This reads the header values from the named environment variables rather than storing them in the file. Codex CLI and the Codex IDE extension share this configuration.

Connecting from Codex Desktop / ChatGPT Desktop

The "Connect to a custom MCP" screen supports headers natively — no config file editing needed:

1. Go to MCPs → Connect to a custom MCP.

2. Name: HALO. Type: Streamable HTTP. URL: https://api.cm.com/halo/core/mcp.

3. Under Headers from environment variables, add three rows:

   • X-CM-PRODUCTTOKEN → HALO_MCP_TOKEN

   • CM-ACCOUNT-ID → HALO_ACCOUNT_ID

   • CM-PROFILE-ID → HALO_PROFILE_ID

4. Save.

(Use plain Headers instead if you'd rather paste the raw values directly — avoid sharing that config with others.)

Ask your agent to set it up for you

If you're using a coding agent that can edit its own MCP configuration, you can paste this instead of doing it by hand:

Add the HALO MCP server to this project using Streamable HTTP at https://api.cm.com/halo/core/mcp. It requires three custom headers: X-CM-PRODUCTTOKEN, CM-ACCOUNT-ID, and CM-PROFILE-ID. Here is my HALO Studio URL https://www.cm.com/en-gb/app/halo-studio/<CM-ACCOUNT-ID>/profile/<CM-PROFILE-ID/ and the Product Token <PRODUCT_TOKEN> — reference them by variable name; don't hardcode the values or write them into a version-controlled file. Show me the resulting configuration before saving it.

Other MCP clients

Any client that lets you configure a remote MCP server with custom HTTP headers will work — Cursor, Windsurf, VS Code, and similar. Use:

• URL: https://api.cm.com/halo/core/mcp

• Transport: Streamable HTTP

• Headers: the three listed above

Not supported yet: claude.ai, ChatGPT web, Claude Desktop's Add Connector screen

These all require OAuth-based authentication in their connector flows and don't currently expose a place to set custom headers, so HALO's MCP server can't be added there today. There's no supported workaround.

E-learning

This video demonstrates the new HALO MCP, a tool that lets you connect HALO to Claude, Codex, or any other MCP-compatible client. You'll see how to create and update agents, wire up tools, and manage MCP server connections, all via natural-language requests rather than manual configuration. The video also shows how to analyze existing conversations to spot gaps or missing tools, then patch an agent on the spot. It's a practical walkthrough of how HALO MCP speeds up agent building and debugging.