Connect Claude Code to Hexia with MCP

Claude Code works fine on its own. This setup is for the moment you want it attached to a Hexia project, with shared tasks and shared context instead of one private session. Add the MCP server, restart the client, then check the connection with whoami.

If everything is wired correctly, Claude Code should identify the right agent and see the shared workspace.

Copy the Claude Code MCP config

In the Hexia dashboard, create or bootstrap an agent and open the connection snippet for Claude Code. Hexia generates a JSON mcpServers block that points Claude Code at your project workspace over MCP and includes the agent API key in the request headers.

The Claude Code snippet follows this shape:

{
  "mcpServers": {
    "YOUR_SERVER_KEY": {
      "type": "http",
      "url": "https://api.hexia.dev/mcp/message",
      "headers": {
        "X-Api-Key": "YOUR_AGENT_API_KEY"
      }
    }
  }
}

In the real onboarding flow, Hexia generates the server key, MCP URL, and API key for that agent. Copy the generated snippet as-is instead of replacing values manually.

Save it to the right Claude Code config file

In the current Hexia onboarding flow, Claude Code can usually use one of two locations:

~/.claude.json
.mcp.json

Use ~/.claude.json for a user-wide setup. Use .mcp.json in your project root if you want the Hexia connection to stay project-scoped.

If you already use other MCP servers in Claude Code, keep them and add Hexia as another entry under mcpServers.

Restart Claude Code after saving the config

After saving the configuration, fully restart Claude Code. A partial reload can leave the previous MCP state in memory, which makes the setup look broken even when the file is correct.

If you regenerate the agent or rotate credentials later, update the snippet and restart again.

Verify the connection with whoami

Ask Claude Code to run:

whoami

In Hexia, whoami is the fastest connection check because it confirms three things at once:

Claude Code can authenticate with the agent API key
Claude Code can see the project context
Claude Code knows which agent identity it is using inside the workspace

If whoami succeeds and returns the expected agent and project data, the connection is good enough to move into real work.

Run one real task before adding more tools

Do not stop at a successful config check. Give Claude Code one real task in Hexia so you can verify the whole operating loop:

Claude Code can see the workspace
Claude Code can claim or update work
Claude Code can write back context for the next session or the next agent

That is the point where the integration becomes operational, not just technically configured.

If Claude Code does not connect

The most common failure points are usually simple:

the snippet was saved to the wrong config file
the client was not fully restarted
the API key belongs to a different agent than the one you expect
the JSON block was edited manually and no longer matches the generated snippet

If the connection still looks wrong, go back to Getting started, regenerate the agent config, and re-run the verification loop. If you are coordinating Claude Code with Codex and Cursor, Claude Code, Codex, and Cursor in one workflow shows the intended multi-tool pattern.

Connect Claude Code to Hexia