This page helps you find out quickly what is broken: the client connection, the key, the server or session sync. Each section is symptom, cause, fix.
The first step is nearly always the same: run status in a terminal with the same variables as in your client config.
MMW_API_KEY=mmw_your_key MMW_ENDPOINT=https://mcp.mmwhub.tech \ uvx --from https://app.mmwhub.tech/downloads/mmw-agent/mmw_agent-0.1.4-py3-none-any.whl mmw-agent statusMMW tools do not appear in the client
Section titled “MMW tools do not appear in the client”Cause 1: no uvx or a suitable Python. The agent needs Python 3.11 or newer and is started through uv.
Fix: install uv, check uvx --version in the same environment the client runs in, and restart the client. GUI clients (Claude Desktop) sometimes do not see your terminal’s PATH; in that case put the full path to uvx in command.
Cause 2: no key. The agent exits immediately with “MMW_API_KEY is not set. Copy the key from your MMW account and put it in the MCP config.” The client reports that the server failed to start.
Fix: add MMW_API_KEY to the config’s env block (not to your shell profile — the client may not read it).
Cause 3: the client was not restarted. The client asks for the tool list when it launches the agent.
Fix: fully restart the client after editing the config.
Only mmw_sync_status is listed and the server is called “MMW (offline, local agent)”
Section titled “Only mmw_sync_status is listed and the server is called “MMW (offline, local agent)””Cause: the MMW server was unreachable when the client started (no network, a proxy, a server restart). The agent answered the client itself so it would not fail, and offered only the local tool.
Fix: check your network and status. The agent retries on every later call, but many clients cache the tool list at start-up — restart the client once the server is reachable.
A tool call returns “MMW server unreachable: …”
Section titled “A tool call returns “MMW server unreachable: …””Cause: the agent could not send the request (network, DNS, timeout).
Fix: try again later and check the address in MMW_ENDPOINT. Session sync loses nothing meanwhile — it catches up automatically.
“MMW rejected the API key (check MMW_API_KEY in the MCP config)”
Section titled ““MMW rejected the API key (check MMW_API_KEY in the MCP config)””Cause: the server answered 401 or 403 — no key, or the key was revoked, expired or copied incompletely. In an organization, your access may have ended (you left, or a contractor term expired).
Fix: copy the key again or issue a new one in your account — see API keys and OAuth. A key is shown once; if you lost it you cannot view it again, only issue a new one.
The same cause is behind ServerError: 401 … printed by mmw-agent status or mmw-agent sync.
Tools work, but the server talks about a subscription
Section titled “Tools work, but the server talks about a subscription”[MMW Notice]: … messages come from the server, not the agent:
| Message | Meaning |
|---|---|
| …has no active subscription, so memory is unavailable | No active subscription; memory is unavailable. |
| …subscription has expired. Memory is read-only during the grace period | Grace period: read-only — search works, remember does not. |
| …account is suspended | The account is suspended because the subscription expired. |
Fix: renew your plan in your account — Plans and billing. Other server errors are in the errors reference.
consent says “Consent must be given by a person in an interactive terminal”
Section titled “consent says “Consent must be given by a person in an interactive terminal””Cause: the command was run outside an interactive terminal — from a script, CI, an IDE task, or by a model. That is by design: a program cannot give consent.
Fix: open a regular terminal and run mmw-agent consent yourself.
consent says “No Claude Code or Codex sessions found on this computer”
Section titled “consent says “No Claude Code or Codex sessions found on this computer””Cause: the agent looks in ~/.claude/projects/*/*.jsonl and ~/.codex/sessions/**/*.jsonl. There are no sessions there, or your clients keep them under a different home directory (for example, another user).
Fix: work in Claude Code or Codex so sessions exist, or point MMW_SESSIONS_HOME at the right directory — in both the terminal and the client config.
Consent was given, but last_cycle.state is consent_required
Section titled “Consent was given, but last_cycle.state is consent_required”Cause: the terminal and the client use different state directories, for example MMW_AGENT_HOME or MMW_SESSIONS_HOME is set in the client config but not in the terminal.
Fix: run consent with the same variables as the client config. The receipt is agent.json inside MMW_AGENT_HOME (default ~/.mmw).
Codex (or Claude Code) sessions are not uploaded
Section titled “Codex (or Claude Code) sessions are not uploaded”Cause: consent covers only the clients whose sessions were on disk when you ran consent. If you started using Codex later, its sessions are not covered.
Fix: run mmw-agent consent again; the agent shows the updated client list.
Nothing is uploaded although consent is in place
Section titled “Nothing is uploaded although consent is in place”Ask the assistant for the sync status (the mmw_sync_status tool) and look at last_cycle:
state | Cause | What to do |
|---|---|---|
idle | The agent just started; no cycle yet. | Wait up to a minute. |
offline | The server is unreachable; the pause between attempts grows up to 5 minutes. | Nothing: the agent catches up on its own. |
server_busy | The server is temporarily low on space and accepted nothing. | Nothing: the agent retries in 5 minutes; the data stays on your disk. |
quota_exceeded | The plan’s history volume is used up (used_bytes, max_bytes). | Change plan, or accept that new sessions are not uploaded. |
unsupported | The server has no session sync. | Check MMW_ENDPOINT. |
error | Unexpected error; details in the error field. | The agent retries; if it persists, contact support. |
ok | The cycle completed. | See the counters below. |
Counters when the state is ok:
skipped_by_plan_history— sessions older than your plan’s history depth; skipped on purpose;conflicts— files the server already accepted in a different form; the agent skips them;truncated— files that became shorter than the accepted part (rewritten or truncated); the agent leaves them alone.
Remember that sync runs only while the agent is running, that is, while the client is open. For a one-off cycle: mmw-agent sync.
revoke says “Local consent removed; server not notified”
Section titled “revoke says “Local consent removed; server not notified””Cause: the server was unreachable when you revoked.
Fix: uploads are already stopped — there is no local receipt. Run mmw-agent revoke again once you are online so the server also unregisters the device.
Agent hints are in the wrong language
Section titled “Agent hints are in the wrong language”Cause: the language follows the server address. If MMW_ENDPOINT is not set, the agent uses its regional default and a different language.
Fix: set MMW_ENDPOINT=https://mcp.mmwhub.tech, or force the language with MMW_LANG=en.