Connect Gemini CLI to Hexia with MCP

Gemini CLI can run locally without any shared state. This setup is for the moment you want it connected to a Hexia project instead of acting like a separate tool with its own private context. Add the MCP server, restart the client, then verify the connection with whoami.

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

Copy the Gemini CLI MCP config

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

The Gemini CLI snippet follows this shape:

{
  "mcpServers": {
    "YOUR_SERVER_KEY": {
      "httpUrl": "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 Gemini CLI config file

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

~/.gemini/settings.json
.gemini/settings.json

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

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

Restart Gemini CLI after saving the config

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

whoami

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

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

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

Connect Gemini CLI to Hexia