Home/Docs/Troubleshooting

Documentation

Troubleshooting

Fix MCP auth errors, empty tool lists, zero credits, and rate limits.

Common issues when using agorch.io and how to unblock them.

MCP authentication fails

Symptoms: Unauthorized / forbidden when chatting with an agent or connecting a client to /mcp.

Checklist:

  • Confirm you are signed in (workspace agents) or that your MCP client has a valid OAuth session or API key.
  • For private agents: re-check the MCP URL and bearer token (or complete OAuth again if the server requires it).
  • For platform MCP (/mcp): create a fresh key under /app/settings/api-keys if the secret may be wrong or revoked. Keys are shown only once.
  • Ensure the key is sent as Authorization: Bearer agorchio_sk_… (no extra spaces).
  • If OAuth fails in an MCP client, retry after signing in at agorch.io/auth in a normal browser, then reconnect the client.

See also Connect your MCP and the Platform MCP reference.

Agent shows no tools (empty tools)

Symptoms: An agent opens but the tool list is empty, or Run UI has nothing to call.

Checklist:

  • The remote MCP HTTP server must be reachable from the internet (or from Agorch’s environment).
  • Trigger a rediscover / sync of tools after the remote server changes its catalog.
  • Verify the agent’s MCP URL path and auth match what the server expects.
  • Temporary upstream outages on the remote MCP will produce an empty or stale catalog — retry later.
  • Catalog agents that are disabled will not appear; private agents only appear for the owning account.

Credits at zero / requests blocked

Symptoms: Chat or MCP calls fail with insufficient credits, or the wallet shows $0.00.

Checklist:

  • Open billing in the workspace and confirm the balance.
  • Top up from /pricing (one-shot Stripe top-ups start at $10). Optional auto-refill can prevent hard stops.
  • New accounts get $1.00 at signup — that balance can run out quickly with heavy tool use (including web search).
  • Credits expire 12 months after they are added (FIFO). Expired credits do not restore automatically.
  • Platform MCP uses the same wallet as in-app chat — there is no separate MCP balance.

More detail: Billing and credits.

Rate limits or soft quotas

Symptoms: Temporary “too many requests” / quota errors even with credits remaining.

Checklist:

  • Soft daily quotas may still apply on top of prepaid credits. Wait and retry, or reduce burst traffic.
  • Avoid tight client loops that spam chat or MCP tool calls.
  • Guest / unauthenticated surfaces are more tightly limited than signed-in workspace usage.
  • If limits persist after a calm period, contact Agorch support.

Still stuck?

Email [email protected] for Agorch product issues. For a third-party agent or remote MCP you connected, use that product’s own support channel.