Agents don't see MCP tools

[ZecaStevenson]

Hi there,

I'm trying to configure MCP tools for the Agents to use, but they don't see them.

I've tried both with stdio MCP tools and with http ones. The example below is using an MCP server hosted by Exa.
The Web-UI has validation fields that make "command" mandatory, but in this case the MCP is not running on localhost and I'm not sure what to put in the command field.

[mcp]
enabled = true
deferred_loading = false

[[mcp.servers]]
name = "exa"
url = "https://mcp.exa.ai/mcp"
api_key_env = "EXA_API_KEY"
transport = "http"

[mcp_bundles.exa]
servers = ["mcp.servers.exa"]

[agents.zeroclaw]
delegate_same_risk_profile = true
enabled = true
model_provider = "together.default"
risk_profile = "balanced"
runtime_profile = "unbounded"
summary_provider = "together.summarizer"
classifier_provider = "together.classifier"
mcp_bundles = ["exa"]

I've also tried with
[mcp.servers.exa]
url = "https://mcp.exa.ai/mcp"
api_key_env = "EXA_API_KEY"
transport = "http"

But the agent does not see the MCP tools.

Zeroclaw is running as a service, using:
/home/{user}/.cargo/bin/zeroclaw daemon --host 0.0.0.0

Any help would be much appreciated!

[ZecaStevenson]

Answering my own question:

It should be:
[mcp_bundles.exa]
servers = ["exa"]

Instead of:
[mcp_bundles.exa]
servers = ["mcp.servers.exa"]

One remaining potential issue - the Web-UI should probably not make the "command" attribute mandatory for http transport.

[ZecaStevenson]

I'm still having issues with the other MCP server though:
https://github.com/yunfeizhu/mcp-mail-server

I've installed it using:
bun install -g mcp-mail-server

Configured it by adding values to /home/{user}/.zeroclaw/.env
IMAP_HOST={hostname}
IMAP_PORT=993
IMAP_SECURE=true
SMTP_HOST={hostname}
SMTP_PORT=465
SMTP_SECURE=true
EMAIL_USER=your-email@{domain}
EMAIL_PASS=your-app-password

Running it manually (for testing) seems to work:
$ bun run mcp-mail-server
=== MCP Mail Server Configuration ===
IMAP: {hostname}:993 (TLS: true)
SMTP: {hostname}:587 (Secure: true)
User: {address}@{domain}
Password: [CONFIGURED]
Configuration loaded successfully
MCP Mail server running on stdio
(aborted since it will be spawned by zeroclaw)

In zeroclaw config:
[[mcp.servers]]
name = "imap"
transport = "stdio"
command = "bun"
args = ["run", "mcp-mail-server"]

[mcp_bundles.imap]
servers = ["imap"]

[agents.emails]
delegate_same_risk_profile = true
enabled = true
model_provider = "together.default"
risk_profile = "balanced"
runtime_profile = "unbounded"
classifier_provider = "together.classifier"
summary_provider = "together.summarizer"
mcp_bundles = ["imap"]

The agent only sees the 2 built-in email tools: email_search and email_read. This is an email address created only to be used with the zeroclaw agent. For now, I'd like the agent to be able to mark and email as read, but later, I'd like the agent to be able to delete emails as well.

Please let me know if I'm missing anything in the config.
Any help would be really appreciated!

[Audacity88]

Thanks for narrowing this down. Your self-correction on the Exa bundle is right: the bundle lists the MCP server name, so this is the right shape:

[mcp_bundles.exa]
servers = ["exa"]

not servers = ["mcp.servers.exa"].

Two other details are worth calling out:

1. The Web UI making command mandatory for transport = "http" looks like a dashboard config-editor bug. Runtime config requires command for stdio, but http / sse servers require url instead.
2. api_key_env is not an MCP server field. For HTTP/SSE MCP auth, use headers, usually an Authorization header. Do not paste the real token publicly, but the config shape is:

[[mcp.servers]]
name = "exa"
transport = "http"
url = "https://mcp.exa.ai/mcp"
headers = { Authorization = "Bearer <token>" }

For the mail server, the important difference is that ZeroClaw is spawning this from the daemon/service environment, not from your interactive shell. A command that works manually can still fail under the service if bun, npx, or the installed package binary is not on the service PATH, or if the mail credentials only exist in a shell-loaded .env file.

I would try this shape first, using either an absolute path to npx or an absolute path to the installed mcp-mail-server binary:

[[mcp.servers]]
name = "imap"
transport = "stdio"
command = "/absolute/path/to/npx"
args = ["-y", "mcp-mail-server"]
env = {
  IMAP_HOST = "<hostname>",
  IMAP_PORT = "993",
  IMAP_SECURE = "true",
  SMTP_HOST = "<hostname>",
  SMTP_PORT = "465",
  SMTP_SECURE = "true",
  EMAIL_USER = "<email>",
  EMAIL_PASS = "<app-password>"
}

[mcp_bundles.imap]
servers = ["imap"]

[agents.emails]
mcp_bundles = ["imap"]

Then restart the affected session/daemon after changing the bundle. MCP bundle grants are resolved when the agent/session is constructed, so editing mcp_bundles while a session is already running will not update that live session.

The logs should tell us which layer is failing. For an eager MCP setup (deferred_loading = false), I would expect to see something like:

Initializing MCP client - 1 server(s) granted via mcp_bundles
MCP: <n> tool(s) registered from 1 server(s), 0 skipped by policy

If instead you see Failed to connect to MCP server 'imap', the next error text should point at the real issue: command not found, missing env, server startup failure, initialize/list-tools failure, etc. If you are running the generated Linux user service, journalctl --user -u zeroclaw.service -n 200 --no-pager is usually the fastest place to check.

One small expectation-setting note: the external tools should show up with the server prefix, for example imap__get_message or imap__delete_message, not as email_*. The built-in email_search / email_read tools are separate ZeroClaw tools, so seeing only those usually means the MCP server did not connect/register.

For marking mail as read, that MCP server appears to expose get_message / get_messages with a markSeen option rather than a separate mark_read tool. Delete is exposed as delete_message, which I would expect to be approval/risk gated rather than silently available in a low-friction profile.

[ZecaStevenson]

Thank you so much for the detailed and precise answer!

The Exa MCP was already working, maybe because I had this on my zeroclaw.service file:
EnvironmentFile=/home/{user}/.zeroclaw/.env

I'll change it to your recommendation to make it cleaner, and as an example I can follow in the future:
headers = { Authorization = "Bearer <token>" }

For the IMAP MCP, this is what worked for me:

I've removed the module as a global module:
bun remove -g mcp-mail-server
Then installed it inside ~/.zeroclaw
bun add mcp-mail-server

I've configured it like this:

[[mcp.servers]]
name = "imap"
transport = "stdio"
command = "/home/{user}/.bun/bin/bun"
args = ["run", "node_modules/mcp-mail-server/dist/index.js"]
env = {
  IMAP_HOST = "<hostname>",
  IMAP_PORT = "993",
  IMAP_SECURE = "true",
  SMTP_HOST = "<hostname>",
  SMTP_PORT = "465",
  SMTP_SECURE = "true",
  EMAIL_USER = "<email>",
  EMAIL_PASS = "<app-password>"
}

journalctl now shows:

MCP Mail server running on stdio

The agent can see the IMAP MCP tools :)