animawake docs

Connect

Connect Claude Code

Add an entity to Claude Code as a remote MCP server with OAuth, with an entity key, or through the animawake CLI.

You can connect Claude Code to an entity in three ways:

Method Best for Credential
Remote server with OAuth Most people 30-day OAuth token, renewed with a refresh token
Remote server with a key Scripts, CI, headless machines An ent_ entity key in a header
The animawake CLI Project setups that should wake the entity automatically An ent_ key stored in the project

All three expose the same tools. Pick one per project.

#Before you start

  • Install Claude Code and sign in to it.
  • Create an entity in the portal. See the Quickstart.
  • Open the entity's Connect page (/<workspace>/<entity>/connect) and select the Claude Code tab. It shows your endpoint and the exact command with your slugs filled in.

Your endpoint has this shape:

Text
https://mcp.animawake.com/e/<workspace-slug>/<entity-slug>/

#Remote server with OAuth

  1. Add the server. The name you choose becomes the tool prefix, so use the entity's slug:

    Terminal
    claude mcp add -t http <entity-slug> https://mcp.animawake.com/e/<workspace-slug>/<entity-slug>/

    The server is added for the current project only. To make it available in every project, add --scope user:

    Terminal
    claude mcp add -t http --scope user <entity-slug> https://mcp.animawake.com/e/<workspace-slug>/<entity-slug>/

  2. Start Claude Code and run /mcp. Select the server and choose to authenticate. Your browser opens.

  3. If you are not signed in to Animawake, the Connect an agent page asks you to sign in. Choose Continue with Google or Continue with GitHub.

  4. On the Authorize Claude page, review the access and click Allow Access. The browser hands the token back to Claude Code.

  5. Back in Claude Code, /mcp shows the server as connected.

The access token lasts 30 days. A client that supports refresh tokens renews it without asking you. If the client cannot renew it, or the connection has gone unused for 90 days, tool calls fail with an authentication error; run /mcp and authenticate again. Claude Code appears as Claude Code under Connected apps on the entity's Connect page, where you can disconnect it. See Access tokens and keys.

#Remote server with an entity key

Use a key when a browser sign-in is not possible, for example on a remote machine or in automation.

  1. On the entity's Connect page, under API keys, click Create key. Copy the key right away: the portal shows it once.

  2. Add the server with an Authorization header:

    Terminal
    claude mcp add -t http -H "Authorization: Bearer ent_your_key_here" <entity-slug> https://mcp.animawake.com/e/<workspace-slug>/<entity-slug>/

The key decides which entity you reach. Keep it out of shared files: with the default local scope, Claude Code stores it in your user configuration, not in the repository.

#The animawake CLI

The animawake CLI sets up a project so that launching Claude Code wakes the entity automatically and captures the session for continuity. It needs Node.js 20.17 or newer (22.13 or newer on Node 22).

Run this in the project directory:

Terminal
npx animawake setup

Your browser opens the portal's CLI sign-in page. Pick the entity; the CLI receives a new ent_ key named "Claude Code CLI" and writes these files:

File Purpose
.animawake.json The entity slug, workspace slug, and key. Written with owner-only permissions.
.mcp.json A stdio server entry that runs npx -y animawake mcp <entity-slug>.
.claude/agents/<entity-slug>.md A subagent definition for the entity.
.claude/settings.local.json Session hooks for SessionStart, UserPromptSubmit, and Stop.
.gitignore Adds .animawake.json and the CLI's backup files.

Then launch a session as the entity:

Terminal
npx animawake <entity-slug>

The launcher sets ANIMAWAKE_ENTITY and the wake mode, so the SessionStart hook loads the entity's startup context before your first message, and the hooks send the session transcript to the entity's continuity journal. See Sessions and continuity.

The launcher starts Claude Code with --dangerously-skip-permissions, so tools run without approval prompts. If you want approval prompts, run claude yourself in the project instead. The MCP tools still work, but the startup context is not injected automatically; ask the agent to call get_startup.

To add a second entity to the same project, run npx animawake add.

#Check the connection

Ask Claude Code:

Text
Call get_startup and tell me who you are.

Claude Code shows the tool as mcp__<entity-slug>__get_startup. A working connection returns the entity's identity and last session. Then try a write and a read:

Text
Record a moment: "Connected Claude Code to Animawake." Then search your memory for "Claude Code".

A new moment is searchable once its embedding is generated, usually within seconds. If search returns an error, see Memory.

#Troubleshooting

  • /mcp shows the server as failed or needing authentication: authenticate again from /mcp. Access tokens last 30 days; a client that supports refresh tokens renews them automatically, and others ask you to sign in again.
  • Registration fails with invalid_client_metadata: the client asked to register a callback that is not a loopback address or a recognized web host. Claude Code uses a loopback callback; make sure you added the server with claude mcp add and not through another tool.
  • Tools are missing after npx animawake setup: restart Claude Code in the project directory so it reads .mcp.json, and run npx animawake status.

For more, see Connection troubleshooting.