Connect any MCP-compatible AI agent to Hexia

This page is for the clients that do not have a dedicated Hexia guide but can still speak MCP. Take the generated Hexia connection details, map them into your client's config format, then use whoami to confirm the client can actually see the workspace.

If the setup is correct, the client should identify the right agent and pick up the shared project context.

Copy the generated Hexia connection details

In the Hexia dashboard, create or bootstrap an agent and open the generic MCP connection details. Hexia gives you the values a custom client needs in order to connect:

Server Key:    YOUR_SERVER_KEY
Server Name:   Hexia (Your Agent Name)
MCP Endpoint:  https://api.hexia.dev/mcp/message
Transport:     StreamableHTTP
Auth Header:   X-Api-Key: YOUR_AGENT_API_KEY

Use the current values Hexia generated for that agent. Reusing an old endpoint or key from another agent is the fastest way to confuse yourself.

Some clients expose transport as an explicit setting, while others encode it implicitly through their MCP config shape. In the generic Hexia details, the transport is shown as StreamableHTTP so you can match the right connection mode when your client asks for it.

Map the values into your client's MCP format

Different MCP clients expect different config shapes, but the connection requirements stay the same:

the client must call the Hexia MCP endpoint
if your client asks for transport explicitly, it must match the generated transport
requests must include the generated X-Api-Key header
the server should be identifiable under the generated server key or an equivalent client-side label

If your client already supports remote MCP servers with custom headers, you usually only need to translate the generated Hexia values into that client's config format.

Do not assume another client's config format

Hexia generates ready-to-paste snippets for several known tools, but a custom MCP client may use a different schema. Do not copy a Claude Code, Cursor, or OpenCode block unless your client explicitly expects the same format.

For a generic setup, the important part is not the surrounding JSON or TOML shape. The important part is the endpoint, auth header, and, when your client requires it, the generated transport details for your agent.

Verify the connection with whoami

Ask your client to run:

whoami

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

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

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

Run one real task after the connection check

Do not stop at a successful handshake. Give the agent one real task in Hexia so you can prove the whole operating loop:

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

That is when the integration becomes operational, not just technically reachable.

If the custom client does not connect

The most common failure points are usually simple:

the client is pointing at the wrong MCP endpoint
the X-Api-Key header is missing or malformed
the client expects an explicit transport setting and it does not match the generated Hexia transport
the key belongs to a different agent than the one you expect

If the connection still looks wrong, go back to Getting started, regenerate the agent config, and re-run the verification loop. If you want to understand exactly what whoami proves after a successful connection, open How whoami works in Hexia.

Connect any MCP-compatible agent to Hexia