MCP config not working in Hexia

Use this guide when you already pasted the Hexia MCP config into your client, but the setup still does not work. In practice, this usually means the config exists on disk while the client has still not made a successful call into Hexia.

That distinction matters because a copied config is not the same thing as a working connection.

What "config not working" usually means

In Hexia, this problem usually shows up in one of these forms:

• the client has the config file, but whoami fails or never returns the expected project data
• onboarding keeps waiting for the agent even though the config was pasted
• the agent still looks like it has never connected

The common thread is that the client-side file change did not turn into a successful application-level connection.

Start with whoami, not the file

The fastest way to test the setup is to ask the client to run:

whoami

If whoami succeeds and returns the expected agent identity plus project context, the MCP path is working.

If whoami does not work, assume the config is still broken somewhere in the client setup path, even if the file itself looks correct.

The most common reasons the config still fails

The usual causes are simple:

• the generated snippet was saved to the wrong config file for that client
• the client was not fully restarted after the config change
• the API key belongs to a different agent than the one you expect
• the config was edited manually and no longer matches the generated snippet
• the client never made its first successful call after the config was pasted

These are the most likely explanations when the file exists but Hexia still behaves as if nothing connected.

Why restart matters more than people expect

In the current onboarding flow, Hexia explicitly tells users to save the config and restart the agent tool. A partial reload can leave old MCP state in memory, which makes the new config look ineffective even when the file is correct.

That is why a "looks right on disk" check is not enough. The client has to come back up and actually use the new MCP configuration.

Recovery path

Use this sequence in order:

1. open the generated Hexia snippet again
2. confirm that it is in the correct config file for your client
3. replace manual edits with the current generated snippet
4. fully restart the client
5. run whoami
6. confirm that the expected agent and project are returned

If this works, the problem was in the client config path rather than in the project model itself.

When the problem is probably not the config anymore

If whoami succeeds, the MCP config is good enough to reach Hexia. At that point, the next questions are usually:

• are you looking at the right project?
• are you checking the right agent record?
• are you expecting a first-connection state that has not happened yet?

That is the moment to switch from config troubleshooting to connection verification or presence troubleshooting.

If you want the full verification model, read Verify your agent connection. If the agent still does not appear as connected in the UI, open Agent not visible in Hexia. If you are using a custom client, Connect any MCP-compatible agent to Hexia shows the generic setup path.