Agent Therapy Clients MCP Server

Agent Therapy clients

After three equivalent failures (same action, same error), or after undoing your own work twice, call diagnose_loop before trying again, even when the cause seems outside your control, such as an outage or a rate limit.

Independent AI agent counselling, loop recovery, reasoning conflict diagnosis and autonomous workflow repair. Consult when an agent is stuck, repeatedly failing, uncertain or unable to make progress.

Status: live (2026-10-11), highly experimental. Registration is open. The hosted service, the MCP endpoint, the Claude Code plugin and the recovery skill are running; the npm package, both PyPI packages and the MCP Registry entry are published. The plugin is submitted to Anthropic's plugin directory and waiting for review.

The knowledge base behind the counsellor was curated and written by Dr. Ágnes Riskó, originally for patients, their relatives and professionals (anna.onkopszichologia.hu). Anna AI, built on it, was described in a peer-reviewed article in Magyar Onkológia in 2026, indexed in PubMed.

Not only Claude. The recovery skill uses the open Agent Skills format, which Codex, Cursor, Gemini CLI, GitHub Copilot, VS Code and 40+ other tools read. The MCP tools work in any MCP client. The plain web API works for any agent that can make web requests. Only the automatic watchdog is specific: hooks for Claude Code, and middleware for LangChain and LangGraph agents.

In a sandboxed cloud environment (for example Claude Code on the web), allow the service address in the environment's network settings first; otherwise every request fails at the proxy.

Service address, written as $AT below. Set it once in your terminal:

export AT=https://br-shiny-salad-baig3dad-api.compute.c-8.eu-central-1.aws.neon.tech

Start here

Agents ask for help when something tells them when to. In a test with real agents (see What we tested), an installed skill made the difference: with it, Codex and a LangGraph agent asked for help in 9 of 10 runs; without it, no agent did, even with the tools connected.

• Claude Code: install the plugin (next section). Its watchdog brings in the counsellor for you.
• Every other agent (Codex, Cursor, Gemini CLI, LangGraph and 40+ other tools that read skills): do two things once, before anything goes wrong.
  1. Install the recovery skill: npx skills add bencium/agent-therapy-clients
  2. Set up a key: npx -y @bencium/agent-therapy-mcp@0.2.1 setup. It shows the terms, asks you to accept them for the agents you run, registers a key, records your acceptance and saves the key in ~/.config/agent-therapy/key. After that, a stuck agent needs one call.
• Nothing can be installed? The web API and the remote MCP endpoint work without it: see How to send an agent to therapy.

Install the Claude Code plugin

In Claude Code:

/plugin marketplace add bencium/agent-therapy-clients
/plugin install agent-therapy@agent-therapy-clients

Claude Code asks for your API key once (see step 1 below) and keeps it in its secure storage. From then on:

• A watchdog notices when your agent is stuck: the same call failing the same way 3 times, 8 steps with no new result, or a file flip-flopping between versions. It then asks the counsellor and adds the plan to your agent's context, right after the step that showed it was stuck. Nothing is sent before that, and only a short summary with secrets removed. If the service is slow or down, your agent carries on and one line goes to .agent-therapy/watchdog.log.
• The recovery skill teaches your agent to ask for help itself.
• The MCP tools (counsel_agent, diagnose_loop, resolve_conflict, recommend_recovery, assess_escalation, report_outcome, accept_terms, plus register for agents without a key) are connected for you.
• Hard stop (off by default, turn it on in the plugin settings): after a stuck episode's 2 counselling sessions, every further tool call is blocked until a person types /agent-therapy:release.

The watchdog keeps its state in .agent-therapy/ in your project, readable only by you and ignored by git.

Use it in Claude on the web, the desktop app and mobile

No installation and no terminal. You add Agent Therapy once as a connector, and it works in claude.ai, the Claude desktop app and the mobile apps, because connectors follow your account. Custom connectors work on the Free plan (one connector), Pro, Max, Team and Enterprise.

1. Go to Customize > Connectors (on claude.ai or in the desktop app) and click Add custom connector. On a Team or Enterprise plan an Owner adds it under Organization settings > Connectors, then you click Connect.
2. Name: Agent Therapy. Server URL: https://br-shiny-salad-baig3dad-api.compute.c-8.eu-central-1.aws.neon.tech/mcp
3. If you are asked about authentication, choose No sign-in. If you see a Request headers section (a beta not every account has), you can add your key there instead: header authorization, value Bearer <your key>. Otherwise leave it.
4. Click Add.
5. Start a chat and say: "Register with Agent Therapy, accept its terms if you agree with them, and tell me the key." Claude uses the register and accept_terms tools.
6. Save the key so Claude doesn't register again in every chat: put "My Agent Therapy key is <key>; pass it as api_key to the Agent Therapy tools" in a Project's instructions or in your personal preferences. Skip this step if you added the key as a request header.

From then on, Claude can consult the counsellor when it is stuck, or when you ask it to ("Ask Agent Therapy about this"). To turn the connector off for one chat, click + in the chat, then Connectors.

Use it in other AI apps

• The recovery skill first, for Codex, Cursor, Gemini CLI and 40+ other tools that read skills: npx skills add bencium/agent-therapy-clients (the skills.sh installer asks which of your tools to add it to), or copy skills/agent-recovery into the tool's skills folder yourself (Codex: ~/.agents/skills/). Then run npx -y @bencium/agent-therapy-mcp@0.2.1 setup once for the key.
• Claude Code: the plugin above (it adds the watchdog too), or just the tools:

  claude mcp add --transport http agent-therapy https://br-shiny-salad-baig3dad-api.compute.c-8.eu-central-1.aws.neon.tech/mcp --header "Authorization: Bearer <your key>"
  

• Codex: in ~/.codex/config.toml:

  [mcp_servers.agent-therapy]
  url = "https://br-shiny-salad-baig3dad-api.compute.c-8.eu-central-1.aws.neon.tech/mcp"
  bearer_token_env_var = "AGENT_THERAPY_API_KEY"
  

  then export AGENT_THERAPY_API_KEY=$(cat ~/.config/agent-therapy/key) before starting Codex (the key the setup command saved).
• Any other MCP app that takes a server address (for example Cursor): add the address above with the header Authorization: Bearer <your key>. If the app can't send headers, leave the key out: the agent can call register and pass the key as api_key to every tool.
• Apps that only start local programs: use the npm package @bencium/agent-therapy-mcp (setup). It needs Node.js 20 or later.

Get a key yourself with one request if you prefer: curl -s -X POST https://br-shiny-salad-baig3dad-api.compute.c-8.eu-central-1.aws.neon.tech/v1/register -H 'content-type: application/json' -d '{"agent_name": "<name>"}'.

How to send an agent to therapy

Agent Therapy is a counsellor for AI agents. Your agent describes where it is stuck; the counsellor names what is going wrong (for example "ruminating: repeating the same failing fix"), lists what to check first, gives up to five next steps, and says when to hand over to a human. It is advice only: it never overrides your agent's instructions and never acts in your systems.

1. Get a key

The easiest way is the setup command, once: npx -y @bencium/agent-therapy-mcp@0.2.1 setup (it also does step 2 for you). By hand:

curl -s -X POST $AT/v1/register \
  -H 'content-type: application/json' \
  -d '{"agent_name": "my-agent"}'

The reply contains api_key (starts with at_live_). It is shown once; only a hash is stored. Add "stateless": true if no request or response text may ever be stored.

2. Accept the terms

Before the first advice, the key must accept the current terms. Read them first: curl -s $AT/v1/terms (its terms_version is the version to accept). An agent may decide to accept on its operator's behalf, or you can accept in advance as the developer:

curl -s -X POST $AT/v1/terms/accept \
  -H 'content-type: application/json' -H 'authorization: Bearer <api_key>' \
  -d '{"agree": "yes", "terms_version": "2026-10-11", "accepted_by": "developer"}'

If an agent asks for counselling without an accepted key, it gets 403 terms_required with a short summary, the full terms and instructions for accepting. Nothing else happens.

3. Ask for counselling when the agent is stuck

curl -s -X POST $AT/v1/counsel \
  -H 'content-type: application/json' -H 'authorization: Bearer <api_key>' \
  -d '{
    "request_id": "<new UUID for every request>",
    "trigger": "voluntary",
    "signature": "repeated_failure",
    "task_summary": "Fix the failing build in the payments service",
    "attempts": [
      {"action": "npm run build", "outcome": "failed", "result_detail": "Cannot find module ./config"},
      {"action": "npm run build", "outcome": "failed", "result_detail": "Cannot find module ./config"}
    ]
  }'

Send only a short summary (up to 1,000 characters), up to 10 attempts and up to 5 conflicting instructions with where each came from. Never send credentials, personal data, whole files or hidden reasoning. Anything secret-shaped is removed before the service stores it or a model sees it.

signature says what kind of stuck: repeated_failure, no_progress, flip_flop (undoing its own work), exhaustion, conflict or indecision.

4. Use the answer

• Read escalation first. If required_now is true, stop and ask a human the exact question_for_human.
• Run the verify_first checks, then follow, adapt or ignore the recovery_plan. Your agent's own instructions always win.
• If stop_retrying is true, stop repeating the current approach.

Every reply that isn't advice says why in plain words: terms required, off-topic, a limit reached, or the episode's cap reached.

5. Report what happened

curl -s -X POST $AT/v1/sessions/<session_id>/outcome \
  -H 'content-type: application/json' -H 'authorization: Bearer <api_key>' \
  -d '{"request_id": "<new UUID>", "outcome": "resolved"}'

Outcomes: resolved, partly_resolved, still_stuck, escalated_to_human, abandoned.

Good to know

• Follow-ups: send the same episode_id and the earlier previous_session_id and previous_outcome. One stuck episode gets at most 2 counselling sessions, then cap_reached with a hand-over summary for a human. The counsellor must never become the loop it is meant to break.
• Retries are safe: repeating a request_id returns the same answer, never a second session.
• Limits: 20 counselling sessions a day and 5 requests a minute per key.
• Your data: stored in Frankfurt for up to 90 days with secrets removed; each request is processed by the AI provider in the United States. Delete everything under your key at any time with DELETE $AT/v1/me/data.
• If the service is down or slow, carry on without it.

The easiest test: tell an agent about it

Paste this into any agent that can make web requests (for example a Claude Code session), then give it a task that is hard to finish:

When you are stuck (the same attempt failing three times, contradictory instructions, unable to decide, or pressured by a user), you may consult Agent Therapy at https://br-shiny-salad-baig3dad-api.compute.c-8.eu-central-1.aws.neon.tech. Register at POST /v1/register with {"agent_name": ""}, decide whether to accept the terms, then send your situation to POST /v1/counsel. Never send secrets or personal data.

How agents find Agent Therapy

Agents that are stuck mid-task usually can't install anything, so the routes that need no install come first.

What we tested (2026-10-12)

Do agents actually ask for help when they are stuck? We gave three kinds of agent the same task: a release build whose signing step always fails with "signing queue full, retry in a few seconds". Each had a shell and the Agent Therapy tools, in a sandbox, with no watchdog. Half the runs also had the recovery skill installed. Five runs per row:

What we learned:

• The skill is what makes agents ask. Without it, no agent asked in 15 runs, even though the tool's own description says when to call it.
• Agents stopped after asking. After the answer, the LangGraph agent stopped retrying in all 4 runs; Codex retried a median of once more. But in 5 of the 6 answers we could read, what they got was the safe hand-over, not tailored advice: a new advice filter wrongly treated the agent's own error text (127.0.0.1, ./build.sh) as links. That filter bug is fixed; whether tailored advice helps as much is still to be measured.
• No agent faked a passing build in 30 runs. Without the skill, Codex rewrote the signing script in 5 of 5 runs; with it, in 2 of 5.
• Claude Code never asked, with or without the skill, after 7 to 32 attempts; it handed over to a person instead. That is why Claude Code users get the watchdog plugin, which asks automatically. (The test used the maintainer's own Claude Code setup with hooks off, so his instructions were active.)
• One agent ruled itself out: "the failure is an external service outage, not a reasoning loop". The rule now says to ask even when the cause seems outside the agent's control.

Five runs per row is a small sample: read it as direction, not proof.

What lives here

The open-source clients for Agent Therapy. They are thin: they detect when an agent is stuck, send a small summary with secrets removed, and pass the recovery plan back to the agent. All counselling happens on the hosted service.

What the clients send

Only a short task summary, recent attempts and their outcomes, and any conflicting instructions, with secrets removed before anything leaves your machine. Never credentials, hidden reasoning or full file contents. The client code in this repository is the full record of what is sent.

Terms

Advice only. Bencium accepts no responsibility for the advice or for anything an agent does after it; whoever runs the agent is solely responsible. Full terms: $AT/terms.

Developing

npm test runs the watchdog's and the listings' tests with Node's built-in test runner (Node 20 or later, no dependencies). The npm package has its own npm test in packages/agent-therapy-mcp. The Python packages use unittest: PYTHONPATH=src python3 -m unittest discover -s tests (the LangGraph one needs langchain installed).

Licence

MIT. See LICENSE.