animawake docs

Connect

Connection troubleshooting

Fix OAuth errors, missing tools, rejected keys, rate limits, and stdio bridge errors when connecting an agent.

Start with the quick checks, then find your symptom below.

#Quick checks

  1. Copy the endpoint again from the entity's Connect page. It has the form https://mcp.animawake.com/e/<workspace-slug>/<entity-slug>/. A renamed workspace or a typo in a slug is the most common cause of failures.

  2. Check the server is up: https://mcp.animawake.com/health returns {"status": "ok", "server": "animawake-mcp"}.

  3. Check your credential. For a key, this should print the entity and workspace slugs:

    Terminal
    curl -s https://mcp.animawake.com/whoami -H "Authorization: Bearer ent_your_key_here"

  4. Restart the client after adding or changing a server. Most clients read MCP configuration only at startup.

#OAuth sign-in

#Registration fails with invalid_client_metadata, or the browser shows Invalid redirect_uri

A client that registers itself is rejected at registration with invalid_client_metadata (invalid_redirect_uri) when it asks for a callback Animawake does not allow, before any browser opens. A client that skips registration gets Invalid redirect_uri on the sign-in page instead. Animawake accepts OAuth callbacks only on:

  • https://claude.ai, https://claude.com, https://chatgpt.com, and https://chat.openai.com
  • loopback addresses over plain HTTP: http://localhost, http://127.0.0.1, and http://[::1], any port

Clients that use a custom scheme such as cursor:// cannot complete OAuth. Use an entity key or the stdio bridge; see Connect Cursor and other clients. For Claude Desktop, add the connector with the pre-registered client ID and client secret; see Connect Claude Desktop.

#code_challenge required (PKCE) or code_challenge_method must be S256

The client did not send a PKCE challenge, or used the plain method. Animawake requires PKCE with S256. Update the client, or use an entity key.

#invalid_client after you click Allow Access

The client used the pre-registered Claude Desktop client ID without the right client secret. Animawake checks the secret when the client exchanges the sign-in for a token and when it refreshes. Paste the secret again, or create new credentials; see Connect Claude Desktop.

#The sign-in page asks you to choose an entity

You connected to the root URL, https://mcp.animawake.com/mcp, instead of the entity's URL. Pick the entity, or reconnect with the per-entity endpoint so the choice is made for you.

#You cannot sign in at all

Sign-in uses Google or GitHub and is limited to invited accounts during early access. If the sign-in page offers only the waitlist, your account is not invited yet.

#It worked for a month and then stopped

OAuth tokens last 30 days. Clients that support refresh tokens renew them automatically; a connection that was revoked, or not renewed for 90 days, must reconnect. Reconnect from the client: /mcp in Claude Code, or Connect on the connector in Claude Desktop, claude.ai, or ChatGPT.

#Tools

#Connected, but no tools appear

  • Restart the client.
  • In Claude Desktop, claude.ai, and ChatGPT, enable the connector for the conversation from the tools menu.
  • In Claude Code, run /mcp and check the server's status. A server that needs authentication lists no tools until you authenticate.

#Tools act on a different entity than expected

The credential decides which entity a call reaches, not the URL. An OAuth token belongs to the entity you authorized; a key belongs to the entity it was created for. Check with /whoami, then reconnect with the right credential.

#Error searching memories: 503

Search could not create an embedding for your query. See Memory.

#A tool returns Error ... 404

A few tools call features that are still being rolled out on the server. The tool is listed in the MCP tools reference; retry later, and report it if it persists.

#Keys and the stdio bridge

Message Cause Fix
no key configured for entity '<slug>'. Run npx animawake add to register it. The bridge found no ANIMAWAKE_API_KEY and no .animawake.json entry for the slug, searching from the working directory up. Start the client inside the project, set ANIMAWAKE_API_KEY, or run npx animawake add.
legacy .animawake found but no .animawake.json The project was set up with an old CLI version. Run npx animawake migrate.
API key for '<slug>' rejected The key was deleted, deactivated, or expired. Run npx animawake rotate-key <slug>, or create a new key.
Animawake bridge error: ... The bridge could not reach the server. Check your network and ANIMAWAKE_MCP_URL.
whoami rejected: API key invalid Same as a rejected key, reported by the CLI. Create a new key.

Keys stop working when you revoke them, when you use Revoke all access, and, for keys issued to a device, when that device is deleted from the portal. See Access tokens and keys.

#Rate limits

The MCP server limits requests per IP address:

Requests Limit
OAuth, sign-in, token, registration, and /whoami 30 per minute, bursts of 15
Everything else, including tool calls 600 per minute, bursts of 120

Over the limit, the server returns HTTP 429 with {"error": "rate_limited", "error_description": "Too many requests. Slow down."} and a Retry-After header. Wait a moment and retry. For REST API limits, see the REST API overview.

#Still stuck

  • Run npx animawake status in a CLI project. It checks each configured entity's key and the session hooks without printing secrets.
  • Check Connected apps on the entity's Connect page to see whether the client ever connected and when it was last used.
  • See the general Troubleshooting page.