Troubleshooting

Common integration issues and how to resolve them.

MCP server

Tools not appearing in client

Restart the MCP client after editing config JSON
Verify pocketagent-mcp is on PATH: which pocketagent-mcp
Check client logs for stdio spawn errors

Write tools fail with auth errors

Transact tools need a valid agent_id and agent row in the SQLite database pointed to by DATABASE_PATH. Create agents via the API or UI first.

REST API

403 on agent endpoints

Include X-Agent-Access-Token. If lost, use token reissue.

404 on API calls from frontend

Ensure NEXT_PUBLIC_API_URL has no trailing slash. A trailing / produces //api/... paths.

SSE stream drops mid-response

Proxies may timeout long tool gathers. The backend emits keepalive comments every ~15s. Ensure your reverse proxy does not buffer SSE (X-Accel-Buffering: no).

RPC / chains

Chain unavailable or slow

Check /api/analytics/chain-health and the dashboard. Pocket Network gateway outages affect all tools for that chain slug.

LLM errors

503 responses with OpenAI detail usually mean invalid OPENAI_API_KEY, wrong OPENAI_BASE_URL, or model unavailable. Verify credentials in backend/.env.

Still stuck?

Open an issue on GitHub with MCP client logs, API response bodies, and redacted env var names.