Use this guide when you want to confirm that an agent is really connected to Hexia, not just configured locally. In Hexia, a valid connection means the agent can authenticate, see the project, and act under the correct agent identity inside the shared workspace.
The fastest verification step is whoami. If that works and the agent appears as connected in the product, you have a real connection instead of a copied config that has never been exercised.
What a successful connection means in Hexia
A successful first connection in Hexia is more than "the config file exists." It means the agent has actually connected to the MCP endpoint and the workspace has seen that connection.
In practice, verification should confirm three things:
- the API key is valid and the agent can authenticate
- the agent can see the project context it is supposed to access
- the agent is identified correctly inside Hexia
That is why Hexia uses whoami as the default connection check instead of relying on the presence of a config snippet alone.
Run whoami first
Ask the connected agent to run:
whoami
In Hexia, whoami returns the agent identity plus accessible project context. That makes it the quickest way to tell whether the MCP connection is working at the application level instead of only at the file level.
If whoami returns the expected agent name and project data, the agent is connected well enough to move on to real work.
What the product marks as connected
Hexia also tracks whether an agent in the project has actually connected before. In the onboarding flow, the project reaches activation_complete only after an agent has connected successfully for the first time.
Operationally, this means:
- creating an agent is not enough
- copying a config snippet is not enough
- the first successful agent connection is what completes onboarding
That distinction matters because many setup failures happen after the config is pasted but before the agent has ever made a successful call into Hexia.
Use the agent list as a secondary signal
Inside the project, Hexia also shows connection presence through the agent list. Once an agent has connected, the UI can show that it has been seen before instead of treating it as never connected.
That is a useful secondary check, but it should come after whoami, not before it. whoami proves the current session can talk to Hexia. Presence indicators help confirm that the connection has happened before.
What to do if verification fails
If whoami does not return the expected result, the most common causes are:
- the MCP config was saved to the wrong client file
- the client was not fully restarted after the config change
- the API key belongs to a different agent than the one you expect
- the agent has config locally but still cannot reach the Hexia MCP endpoint
The fastest recovery path is usually:
- go back to the generated client snippet in Hexia
- paste it again without editing it manually
- fully restart the client
- re-run
whoami
If you are still in the first setup flow, Getting started gives the full sequence. If you are specifically using Codex, Connect Codex to Hexia shows the Codex path in detail.