Quick fixes for the issues integrators hit most often. For credential definitions, see Credentials cheat sheet.

​
MCP returns 401 Unauthorized

Symptoms: tools/list or tools/call fails with missing/invalid credentials. Checks:
  1. Header is Authorization: <api-key> or X-API-Key: <api-key> — no Bearer prefix unless your client adds it consistently.
  2. Key is the application API key from Agentic Stack → Overview (not a wallet accessKey).
  3. Key matches the same application you created agents under.
  4. Key is not expired or rotated in the dashboard without updating env / mcp.json.
Message: Invalid API key — validation failed against Kong; re-copy from Overview. Message: Missing credentials — no header sent; fix MCP client or curl -H.

​
No active agents exist for this app

Symptoms: Wallet tools fail; discovery may still work. Cause: Agents are created via createAgent (SDK) or REST POST /agents, not from the dashboard UI alone. Fix:
  1. Run SDK quickstart once for a test user.
  2. Confirm the agent appears under All agents and status is Active.
  3. Retry MCP with agent_id if you have multiple agents.

​
Multiple active agents — pass agent_id

Symptoms: 
Multiple active agents exist for this app. Pass agent_id in tool arguments (or X-Agent-Id header) to select which agent to use.
Cause: Application API key with more than one active agent; MCP cannot pick safely. Fix: Add to every wallet tool call: 
{ "agent_id": "<uuid-from-all-agents>" }
Or send header X-Agent-Id: <uuid> on the MCP HTTP request. Production tip: One agent per end-user identity; always pass agent_id explicitly instead of relying on “most recent agent” dev behavior.

​
agent_id does not match customer API key

Symptoms: 403 Forbidden when using a per-agent API key as Authorization. Cause: agent_id in arguments refers to a different agent than the key is bound to. Fix: Omit agent_id when using per-agent agent.apiKey, or pass the matching UUID only.

​
No agents exist — create via REST first

Symptoms: No agents exist for this app. Create an agent via REST before calling MCP tools. Fix: Call createAgent before wallet MCP tools. discover_services / get_service / tools/list do not need agents. Symptoms: First paid_fetch call returns JSON-RPC error -32402 or a paymentRequired object — not a bug. Cause: The HTTP API requires x402 payment before returning data. Fix:
  1. Treat as success path: parse accepts[] from the response.
  2. On your backend, sign paymentPayload with the agent’s accessKey (x402 payments).
  3. Retry tools/call with paymentPayload at the top level of params (sibling to name / arguments).
IDE note: Cursor alone cannot sign unless you run a local Node script with stored accessKey.

​
Insufficient funds / transfer preflight fails

Symptoms: transfer or signing fails; balance tools show low native balance. Fix:
  1. Call get_wallet_address for the agent’s EVM address.
  2. Fund that address with native gas on the target chain (ETH on Base, etc.).
  3. For token transfers, ensure token balance on the same chain.

​
transfer returns unsigned transaction — nothing broadcast

Symptoms: MCP returns unsigned_transaction_ready or similar; chain state unchanged. Expected: Agent Kit does not submit transactions. Your backend must sign with accessKey and broadcast (see AgentSigningService in the sample backend API).

​
accessKey lost after createAgent

Symptoms: Cannot sign; only have application API key. Cause: wallet.accessKey is shown once at agent creation. Fix: There is no dashboard “reveal access key.” Create a new agent (or follow your product’s key-rotation flow) and store the new key encrypted immediately.

​
Claude / ChatGPT connector shows wrong or generic icon

Symptoms: Connector works, but the sidebar shows an old logo, generic MCP triangle, or globe instead of the Abstraxn icon. Cause: The client fetches branding from your MCP host (/favicon.png, OAuth logo_uri, or MCP initialize → serverInfo.icons). If Kong returns 401 on favicon paths, or the connector cached an icon from an earlier failed fetch, you see a placeholder. Fix:
  1. Confirm public favicon (no API key):
curl -sS -D - -o /dev/null "https://abstraxn.com/icon.png"
# Expect: HTTP 200, content-type: image/png
  1. Confirm OAuth metadata includes logo_uri → https://abstraxn.com/icon.png:
curl -sS "https://agent-kit.abstraxn.com/.well-known/oauth-authorization-server" | jq '.logo_uri'
  1. Ask infra to bypass Kong key-auth on GET /favicon.ico and GET /favicon.png (see External agents — Connector icon).
  2. Disconnect and re-add the connector in Claude or ChatGPT so the client refetches branding.

​
Cursor does not show MCP tools

Checks:
  1. url ends with /mcp and uses "transport": "http".
  2. Authorization header value is the raw application API key.
  3. Restart Cursor after editing config.
  4. Run 5-minute smoke test with the same key — if curl works but Cursor does not, the issue is IDE config.

​
Dashboard Tools page empty or errors

Checks:
  1. Application selected in the sidebar dropdown.
  2. Agent Kit provisioned for that app (created with application).
  3. API key in Overview matches the app you are viewing.

​
Spend policy denied (-32403)

Symptoms: MCP JSON-RPC error -32403 on a paid or restricted tool. Cause: Agent or app spend policy blocked the action (limits, allowlists). Fix: Review agent status, plan limits (Pricing), and dashboard activity logs for the agent.

​
FAQ

​
Can I call MCP from the browser?

No. Keep the application API key and accessKey on your server. The frontend should call your JWT API only (Full-stack app integration).

​
Do I need both application API key and per-agent apiKey?

No. Most apps use only the application API key + agent_id per user. Per-agent keys are optional for stricter scoping.

​
Which tools need agent_id?

With an application API key, any tool that acts on a specific agent wallet needs a resolved agent — pass agent_id when you have multiple agents. Whether a tool requires agent_id is defined in its inputSchema from tools/list or the dashboard Tools page.

​
Can I test x402 without a backend?

You can run discover_services from curl or Cursor. paid_fetch payment completion requires backend signing with accessKey.

​
Still stuck?

  1. Re-run the smoke test and note the exact error message.
  2. Compare env vars to Credentials.
  3. Contact Abstraxn support with app id, agent id (if any), and redacted error text.