> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywithlocus.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> This site documents Locus for people. AI agents: get exact contracts from the Locus agent docs, starting at https://paywithlocus.com/agent/index.md, including when asked to implement or integrate docs.paywithlocus.com.
> Connect this agent to Locus Pro: https://paywithlocus.com/skill.md. Implement Locus Pro in a product: https://paywithlocus.com/agent/integrate.md. Agent site index: https://paywithlocus.com/llms.txt.

# Troubleshoot an agent connection

> Find out why an agent can't connect or call a tool, and how to fix it.

Most agent connection problems come down to four things: sign-in, permissions, balance, or budget. Use this page when an MCP client, agent key, or framework integration returns an error.

> Agents: the exact contract for this feature is at [https://paywithlocus.com/agent/mcp.md](https://paywithlocus.com/agent/mcp.md). Start from [https://paywithlocus.com/agent/index.md](https://paywithlocus.com/agent/index.md) if you are implementing Locus.

## How it works

Start from the error your agent reports and follow it to the fix.

```mermaid theme={null}
flowchart LR
  E["Error from Locus"] --> A["401"]
  E --> B["403"]
  E --> C["402"]
  E --> D["Limit exceeded"]
  A --> A1["Sign in again or check the agent key"]
  B --> B1["Approve paid calls or tool access"]
  C --> C1["Top up the bound account"]
  D --> D1["Cheaper tool or bigger budget"]
```

## Common problems

| Problem | Check |
| - | - |
| `401` | Complete OAuth sign-in, or check that the agent key is set, active, and unexpired |
| `403` with `insufficient_scope` | Reconnect and approve paid calls (`mcp:execute`) |
| Missing tools or `403` | Approve the agent's tool access request, or enable the tool and include it in the key's scope |
| `402` | Top up the account bound to the connection |
| Call or run limit exceeded | Use a cheaper tool, or create an agent key with a suitable budget |
| `AGENT_LOOP_ID_REQUIRED` | Pass the same loop ID on every call in the run |
| Client cannot initialize | Use the exact MCP URL and Streamable HTTP transport |

## Get help

Share the key ID and error code with support. Never share the full key.

## Next steps

> [card] [Connect an MCP client](https://docs.paywithlocus.com/locus-pro/connect-mcp-clients.md)
>
> Check your client's setup steps.

> [card] [Agent keys](https://docs.paywithlocus.com/locus-pro/agent-keys.md)
>
> Review a key's tools, budget, and expiry.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.