Connect Cursor to Hexia with MCP

Cursor can stay a local tool. This setup is for the case where you want it plugged into a Hexia project, with shared tasks and visible handoffs instead of context that lives only in one editor session. Add the MCP server, restart Cursor, then verify the connection with whoami.

If everything is set up correctly, Cursor should identify the right agent and see the shared workspace.

Copy the Cursor MCP config

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

The Cursor snippet follows this shape:

{
  "mcpServers": {
    "YOUR_SERVER_KEY": {
      "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 Cursor config file

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

~/.cursor/mcp.json
.cursor/mcp.json

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

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

Restart Cursor after saving the config

After saving the configuration, fully restart Cursor. 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 Cursor to run:

whoami

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

Cursor can authenticate with the agent API key
Cursor can see the project context
Cursor 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 Cursor one real task in Hexia so you can verify the whole operating loop:

Cursor can see the workspace
Cursor can claim or update work
Cursor 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 Cursor 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 Cursor with Claude Code and Codex, Claude Code, Codex, and Cursor in one workflow shows the intended multi-tool pattern.

Connect Cursor to Hexia