Troubleshooting

Ask your agent app, “What are my Agent Connect balances?” It lists its accounts with get_accounts and checks balances with get_balances, using source: confidential for account funds. These read-only calls test access without attempting a payment.

MCP Tools Are Missing

Model Context Protocol (MCP) lets your agent app use Agent Connect tools.

• Restart the app, or open a new session. Servers added during a session load only in a new one.
• Confirm the app has the Agent Connect MCP URL exactly as shown in the app, ending in /mcp.
• Confirm you finished signing in. The app shows the server as needing authentication until you do.
• Confirm the app supports remote MCP over HTTP with OAuth sign-in.

The Browser Did Not Open

Copy the sign-in URL printed by your client and open it in your browser. In Claude Code, type /mcp, choose agent-connect, and choose Authenticate. In the Codex CLI, run codex mcp login agent-connect; in the Codex app, open Settings → MCP plugins and choose Authenticate. In Grok Build, type /mcps, select agent-connect and press i. In Hermes, run hermes mcp login agent-connect. In OpenClaw, run openclaw mcp login agent-connect in your terminal and open the link it prints, even if the agent says its chat tools cannot start OAuth.

The Consent Screen Asks Me to Create an Agent

An app needs an agent to connect to. If you have none, the consent screen creates the first one: it suggests the app’s name, you confirm with one signature, and you carry on to allow the app. If you have agents, choose New agent to do the same. You can set limits and destinations later in the dashboard.

The Client Is Not Connected

Agent Connect shows Connected with the client’s name once the client is bound to your agent. If that status has not appeared, complete the browser sign-in and the signature requests, then ask the app for its balances.

A 401 Error With an API Key

• The key expired or was revoked. Keys last 30 days. Replace it from API Key in the dashboard’s Agent Integrations.
• The environment variable is not set in the shell that launched the client. Claude Code warns about this and sends the literal text ${AGENT_CONNECT_KEY} as the key. Set AGENT_CONNECT_KEY, then start the client from that shell.
• The key was issued for a different agent than the one you expect.

Never paste a live key into a prompt, chat, or support request.

Claude or Grok on the Web Cannot Connect

Claude Desktop, claude.ai, Cowork, grok.com and Grok Bot connect from their provider’s cloud, so the MCP URL must be reachable from the public internet. A local or private address does not work. Use an app that runs on your machine, such as Claude Code, Codex or Hermes, for a local setup.

The Connection Expired or Was Disconnected

Connect again: sign in through your app and complete the signature requests for the accounts you need. For an API key, issue a new one from the dashboard.

An Account Is Missing

Compare the accounts returned by get_accounts with those you selected when the app signed in. Use the exact returned name. Creating an account or adding funds does not give an existing connection permission to use it. Connect the app again to add the account.

Balance Calls Fail

Check the account name, account permissions, and source: confidential. Public balance reads are unavailable. Listing accounts successfully does not prove that every balance check will succeed.

An Older Account Needs a Policy Update

Confidential operations require a confidential account policy. Apply the requested policy update with the owner’s signature. A policy update changes execution rules; it does not transfer an older balance into the confidential balance.

A Transfer Waits for Approval

If you enabled human review, open the review link returned with the request. After approving or rejecting it, check the existing transfer instead of submitting another one.

A Transfer Is Blocked or Delayed

Read the reason shown. Check the saved rules, amount left to spend, timelock, the account whitelist, Account Hold, and balance. Repeating a request does not bypass the rules or shorten a delay.

A Payment’s Result Is Unclear

Check the existing request before trying again. Wait for a confirmed result before sending another payment. If you are writing an integration, reuse its idempotency_key only when retrying the same request with unchanged details.

A Deposit Is Missing

Check the asset, network, deposit address, memo or tag, minimum amount, and deposit status. Processing time depends on the deposit route. Check for completion or a refund into the agent balance before sending again. Each deposit address takes one deposit only: a second send to the same address is not credited or refunded, so create a new deposit address instead of reusing it.

Ask for Help

Include the app, step, error message, and whether the app can list accounts and read balances. Remove API keys, Authorization headers, recovery information, and private configuration from logs or screenshots.