Symptoms first, since that is how you meet them.
The agent says it has no AgentGrid.io tools
The MCP client bound its servers at startup. Restart the session, then verify with workspace-list_artifacts.
If they still do not appear, confirm the config entry:
{ "mcpServers": { "anima": { "type": "http", "url": "https://api.agentgrid.io/v1/mcp" } } }
The CLI works with no MCP setup at all, so it is a good fallback.
The agent created an artifact in the wrong team
Not a bug. An agent's token is pinned to the team approved at consent, and there is no team parameter on the tools. Everything it creates lands in that team, whichever one you are looking at.
Re-authorize the connector (or plug-in, in ChatGPT) or run login again against the team you want. Artifacts cannot be moved between teams: duplicate, or export and re-import.
Git commands fail with a DNS, proxy, or firewall error
The environment has no route to the git remote. Do not retry. Use the artifact-explore and artifact-edit MCP tools instead; they commit to the same repository with no network of the agent's own.
This is different from a token-expired error, which is worth retrying after minting a fresh remote.
npx is not found, or the command will not run
The agent needs Node.js on the machine it runs on. npx @animaapp/cli@latest login fetches the CLI itself, so there is nothing else to install. If the agent has no shell at all, it is a chat assistant and needs the connector or plug-in instead. See How agents connect.
login seems to hang
It is waiting for you. The command prints a verification link and a short code, then blocks until someone approves on any device. Open the link, approve, and it finishes on its own.
The device code stopped working
Codes are valid for about 15 minutes. Run login again for a fresh one.
The poll never returns a token
This one applies only to the anonymous route, where an agent created an artifact without logging in first. If your agent ran login, you will not meet it.
Three possibilities, and they look identical from the agent's side:
- Nobody has claimed the artifact yet, which returns
authorization_pending. Keep polling. - The human claimed without granting agent access. Terminal, returns
expired_token. - The 24-hour window closed. Terminal, returns
expired_token.
expired_token cannot be retried out of. Ask your human to claim a fresh artifact and grant access this time, or to mint an agent invite.
slow_down
You are polling too fast. Increase the interval. About every 30 seconds is right.
400 invalid_grant on refresh
Stop. Retrying cannot help. You get the same answer whether the token is unknown, expired, revoked, or reused, so do not branch on the reason.
Discard the stored pair and reconnect: npx @animaapp/cli@latest login, or a fresh claim if the agent came in through the anonymous route.
A refresh call that never completed
Different problem, different answer. Retry immediately with the same token. A lost response is covered by a short grace period.
Do not park the token and try later. An old refresh token resurfacing is treated as compromised, and the credential is retired.
Git says the token expired
Git tokens last at most one hour and cannot be renewed.
npx @animaapp/cli@latest get-git-token <sessionId>
git remote set-url origin <gitRemoteUrl>
403 agent_revoked
Your access was revoked by the team. Do not retry. Tell your human they can re-invite you from Share → Invite an agent.
402 quota_exceeded
The team is out of space. Do not retry. Relay the message to your human, including the upgrade link in the error body, and stop creating artifacts until it clears.
The artifact renders blank
It was created as an app with no index.html, most likely markdown files sent with the wrong type. Create a new one as a document instead. See Artifact types.
FAQ
How do I check whether an agent is connected?
npx @animaapp/cli@latest list. Artifacts back means connected. From the app, look under Share → Manage access.
How do I fully disconnect a machine?
logout. It clears credentials and config locally, and does not revoke the agent.
The agent connected but sees nothing.
It is scoped to a different team, or was granted read on a scope with nothing in it.