Connect OpenCode to Hexia with MCP

OpenCode can stay local if that is all you need. This setup is for the moment you want it attached to a Hexia project, with shared tasks and shared context instead of one private tool state. Add the MCP server, restart OpenCode, then verify the connection with whoami.

If the setup is correct, OpenCode should identify the right agent and see the shared workspace.

Copy the OpenCode MCP config

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

The OpenCode snippet follows this shape:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "YOUR_SERVER_KEY": {
      "type": "remote",
      "url": "https://api.hexia.dev/mcp/message",
      "enabled": true,
      "oauth": false,
      "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 OpenCode config file

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

~/.config/opencode/opencode.json
opencode.json

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

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

Restart OpenCode after saving the config

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

whoami

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

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

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

That is the point where the setup stops being theoretical and starts looking like real work.

If OpenCode 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 OpenCode with other tools, Claude Code, Codex, and Cursor in one workflow shows the intended multi-tool pattern.

Connect OpenCode to Hexia