MCP wiring

When your harness can't see agentry's tools — or sees them but can't call them.

Harness lists 0 agentry tools

You added agentry to your MCP config, restarted, and the agent doesn't list any agentry tools.

Order of checks (most common first):

1. agentry isn't on the harness's PATH

The most common cause. Harnesses launched from the dock or app launcher don't always see the same PATH as your terminal.

Test:

which agentry
# /Users/you/.local/bin/agentry

Now use the absolute path in your MCP config:

{
  "mcpServers": {
    "agentry": {
      "command": "/Users/you/.local/bin/agentry",
      "args": ["mcp"]
    }
  }
}

Restart the harness.

2. The CLI isn't signed in

Test in a terminal:

agentry mcp

It should print nothing and wait for input (it's an MCP server). Hit Ctrl-C.

If instead it errors "not logged in":

agentry login

Then restart the harness.

3. Bad JSON in the config

A trailing comma, quote mismatch, or unquoted key breaks the whole MCP config block.

cat ~/.claude/claude_desktop_config.json | python3 -m json.tool
# or for Cursor:
cat ~/.cursor/mcp.json | python3 -m json.tool
# or Continue:
cat ~/.continue/config.json | python3 -m json.tool

python3 -m json.tool will print an error pointing at the offending character. Fix it, save, restart the harness.

4. The harness didn't actually restart

"Closing the window" isn't enough for harnesses that run as background apps. Full quit:

• macOS: Cmd-Q with the app frontmost.
• Windows: Right-click the tray icon → Quit (or kill via Task Manager).

Then relaunch.

5. An old MCP session is cached

Some harnesses cache their MCP server list. Check the harness's docs for how to refresh; usually a full quit + relaunch is enough.

Harness lists tools, but tool calls fail

The agent tries sandbox_create and gets an error.

"no server set" / "no cluster current"

You haven't picked a server as the current. From a terminal:

agentry server ls
agentry server use <name>

Then have the agent retry.

"rate limit exceeded"

You hit a rate limit on the agentry control plane. Almost certainly a runaway loop in the agent. Pause the chat, give it 30 seconds, retry.

"unauthorized"

Your auth token expired or was revoked. Re-login:

agentry login

Restart the harness.

Tool list includes outdated tools

Your harness shows old tools that aren't in the CLI anymore (e.g. a deploy tool). The agent tries them and they fail.

Cause: the agentry CLI itself is old. Some tools were renamed or removed; your harness is showing a cached schema from an old MCP session.

Fix: reinstall the CLI to pick up the latest version.

curl -fsSL https://agentry.run/install.sh | sh

Then quit + relaunch the harness so the new CLI mints a fresh schema.

Tool descriptions look wrong

The tool list shows agentry tools but their descriptions are vague or out of date.

Cause: same as above — old CLI.

Fix: reinstall via curl -fsSL https://agentry.run/install.sh | sh, restart harness.

The agent never calls agentry tools, only writes code locally

Your harness has agentry wired correctly, the agent acknowledges the tools, but it writes files directly on your local machine instead of in an agentry sandbox.

Cause: the agent's system prompt or the harness's default behavior is biased toward local file edits.

Fix: be explicit in the prompt:

Use agentry's sandbox_create to make a fresh sandbox. Then use file_write to write files in the sandbox, not in this repo. All work should happen on the agentry server, not locally.

For harnesses like Claude Code and Cursor that have a deep model of the local filesystem, you may want to also keep a separate prompting profile for agentry sessions vs. local sessions.

"spawn agentry ENOENT"

Error: spawn agentry ENOENT

The harness tried to launch agentry mcp but couldn't find the binary. See 1. agentry isn't on the harness's PATH.

"agentry mcp exited unexpectedly"

The MCP server crashed. Run it manually:

agentry mcp

If it errors, fix the underlying issue (usually auth or network — see above). If it runs without error and exits when you Ctrl-C, the harness's process management is probably trying to send signals it doesn't handle — update both your harness and the CLI to latest.

Reading MCP logs

agentry mcp logs to stderr — connection state, tunnel re-dials, and tool errors all go there. Most harnesses surface MCP stderr somewhere (a logs panel, or a file in their data directory); check there first.

To watch it directly, run the server in a terminal:

agentry mcp

It waits for input on stdin (normally the harness's job) and prints status to stderr. Hit Ctrl-C to stop.

Next

• Per-harness setup — start over from clean configs.
• Connection issues — if the server side is the problem.
• Sandbox issues — once MCP is working but tool calls misbehave.