# Build with AnimaGuru > Connect AI agents and code to AnimaGuru: the remote MCP server, the CLI, the REST API and its OpenAPI spec, authentication and credits. AnimaGuru generates images, characters and sprite animations, video, music, speech and sound effects, and keeps them together in projects. People use it in the browser studio. Agents and code use it through a remote MCP server, a command-line interface and a REST API, all backed by the same account, projects and credits. ## When to use AnimaGuru Reach for AnimaGuru when someone wants original creative assets made for them and kept in one place: - Illustrated characters and props, and sprite animations of them: idle, walk, run, jump, punch, hurt and other actions, or a custom motion described in words. Exports include sprite sheets and animation data for games. - Images and short videos from text or images, including first/last-frame references, clip extension and audio references where the configured model supports them. - Music, speech in a range of voices, and sound effects. - Short animated films: the CLI scaffolds a local video workspace with 31 visual styles that a coding agent fills with generated assets and exports to MP4. The CLI assembles local films with PixiJS for browser playback and HTML5 or MP4 export. AI generation runs asynchronously and spends the connected account’s credits; creating projects, browsing and estimating are free. Use current model profiles, validate the request and review its cost before paid work. ## Pick a surface - Chat assistants and other MCP clients (ChatGPT, Claude and any client with remote MCP and OAuth): connect the [MCP server](#mcp). - The AnimaGuru ChatGPT plugin is **coming soon** and currently in review for the ChatGPT directory. It brings project browsing, media playback, frame inspection and generation review into your conversation. See its preview in the [agent setup guide](https://animaguru.com/agent-setup.md). - Coding agents working in a folder (Codex, Claude Code): install the [CLI](#cli). The [agent setup guide](https://animaguru.com/agent-setup.md) walks through it. - Scripts and backends: call the [REST API](#rest-api) described by [the OpenAPI document](https://animaguru.com/openapi.json). ## MCP server The server uses the Streamable HTTP transport at this address: MCP URL: ``` https://animaguru.com/mcp ``` It signs people in with OAuth 2.1: the authorization code flow with PKCE (S256) and dynamic client registration. Clients find everything from the server's 401 response, which points at [the protected resource metadata](https://animaguru.com/.well-known/oauth-protected-resource) and [the authorization server metadata](https://animaguru.com/.well-known/oauth-authorization-server). The scopes are `projects.read` and `projects.write`; access tokens last one hour and refresh tokens 30 days. Tools cover the whole studio: `list_workspaces`, `list_projects`, `get_project`, `create_project`, `move_work`, `list_assets`, `estimate_generation`, `generate_character`, `animate_character`, `redraw_character`, `generate_custom_animation`, `generate_asset`, `list_avatars`, `list_avatar_looks`, `get_avatar`, `list_avatar_templates`, `create_avatar`, `create_avatar_looks`, `update_avatar`, `request_avatar_consent`, `search_motion_examples`, `get_motion_example`, `list_motion_categories`, `search_asset_library`, `get_library_asset`, `import_library_asset` (Pro and Team plans), `list_jobs`, `get_job`, `get_ui_snapshot`, `get_profile` and `open_studio`. Read-only tools carry `readOnlyHint`. In clients that support MCP Apps, `open_studio` renders an interactive studio (`ui://animaguru/studio/v4.html`) with project pickers, animation playback and generation review. Create neutral project containers and choose a style for each sprite request. Use `redraw_character` for whole artwork revisions and `generate_custom_animation` for named motions; these do not edit single frames in place. Read configured models and video profiles with `list_assets`, validate with `estimate_generation`, and poll `get_job` using its returned interval until it finishes. The avatar tools browse HeyGen's public avatars from any project and create a project's own from a prompt, a photo or footage; an avatar a project creates is visible only to that project, and a new look is polled with `get_avatar` until it completes. MCP does not expose project or avatar deletion, local ZIP export, film scaffolding, cloud sync or YouTube publishing; use the CLI for supported local workflows. The server card is published at [/mcp/server-card](https://animaguru.com/mcp/server-card). ## Command-line interface The `animaguru` command needs Node.js 24 or later. Install it from npm, or on macOS with the installer script: npm: ``` npm install -g @docyrus/animaguru ``` macOS: ``` curl -fsSL https://animaguru.com/install.sh | bash ``` Sign in once. The browser opens a device-code approval page, and the CLI stores a revocable seven-day session: Sign in: ``` animaguru auth login animaguru auth status animaguru credits ``` For assets in an existing game or app, run `animaguru init` in that folder, then use `projects`, `jobs`, `assets` and `files` to generate, inspect and download artwork or export sprite ZIPs. For one film use `animaguru create my-video`; for shared branding use `animaguru create workspace my-brand`, then `animaguru create animation first-film` inside it. New workspaces include AGENTS.md, CLAUDE.md, creative skills and PixiJS guidance. Existing folders are not replaced by create. Local films support HTML5 and MP4 exports, subtitles, posters and multiple language cuts. `animaguru submit` hosts finished films privately, and `videos` manages the library and private sharing. Public gallery publication requires accepting the sharing agreement on the website and staff approval. `animaguru youtube` uploads exported MP4s directly from your computer with a separate Google Desktop OAuth connection; it does not use AnimaGuru generation credits. Inspect `--help` and `animaguru schema` for current flags. Every command prints JSON on success and exits nonzero on errors. `animaguru catalog` lists art styles, actions, asset types, models and voices; `animaguru schema` prints the full command schema; `animaguru init` installs the AnimaGuru skill for your coding agent; `animaguru create my-video` scaffolds a video workspace. Agent runners can inject a token with the `ANIMAGURU_TOKEN` environment variable instead of signing in. The package is [@docyrus/animaguru on npm](https://www.npmjs.com/package/@docyrus/animaguru). On Individual Pro and Team, `animaguru cloud` syncs a video workspace with every version. `cloud link` creates the cloud project, `cloud push -m` saves a version, `cloud pull` brings in versions saved elsewhere, `cloud restore` returns to an earlier one and `cloud clone` continues on another computer. Dependencies, exports, `.env` files, credentials and `.gitignore` matches stay local. Browse versions and download files on the [Cloud page](https://animaguru.com/app/cloud). Cloud sync: ``` animaguru cloud link animaguru cloud push -m "First cut" animaguru cloud pull animaguru cloud versions ``` ## REST API The API serves JSON from `https://animaguru.com/api`. [The OpenAPI 3.1 document](https://animaguru.com/openapi.json) describes every operation with request and response schemas, and [the API catalog](https://animaguru.com/.well-known/api-catalog) links it for automatic discovery. A few endpoints are public: `GET /api/health`, the public video gallery at `GET /api/videos`, and credit pack information at `GET /api/billing`. Everything under `/api/v1` acts for a signed-in account and needs a bearer token: Check your balance: ``` curl https://animaguru.com/api/v1/credits \ -H "Authorization: Bearer $ANIMAGURU_TOKEN" ``` A typical flow: list projects with `GET /api/v1/projects`, or create one with `POST /api/v1/sprites`. Price a job with `POST /api/v1/sprites/{id}/jobs/estimate` or `POST /api/v1/sprites/{id}/assets/estimate`, queue it with the same body on `/jobs` or `/assets`, then poll `GET /api/v1/sprites/{id}/jobs/{jobId}` until it finishes. Send an `Idempotency-Key` header when submitting so a retried request does not queue the job twice. Errors use HTTP status codes with a JSON body of the form `{ "error": { "message": "…" } }`. A missing or expired token returns 401. ## Authentication - MCP clients: OAuth 2.1 with PKCE, as described above. Nothing to configure beyond the server URL. - CLI and REST API: the OAuth 2.0 device authorization grant. Request a code with `POST /api/auth/device/code` and the client ID `animaguru-cli`, open the returned `verification_uri_complete` to approve it while signed in, then poll `POST /api/auth/device/token` with `grant_type` set to `urn:ietf:params:oauth:grant-type:device_code`. The response's `access_token` is the bearer token. `animaguru auth login` does all of this for you. - Accounts are self-serve and free to open: anyone can [create an account](https://animaguru.com/register) in the browser, and new accounts start with 30 free credits to try AnimaGuru. Tokens act with the signed-in person's access, including team workspaces they belong to. [auth.md](https://animaguru.com/auth.md) restates these steps for agents. ## Credits and safe testing New accounts start with 30 free credits to try AnimaGuru, and more come in one-time credit packs; no subscription is needed to generate. Generation spends credits from the personal or team workspace that owns the project; creating projects, listing, inspecting and estimating are free. MCP `estimate_generation` and generation tools with `dry_run: true`, plus REST `/estimate` endpoints, validate against the server without queueing work or spending credits. CLI `--dry-run` estimates use bundled rates and do not verify server model configuration, reference ownership or remaining balance; the server checks these on submission. Show the estimate before paid work. CLI paid submissions require `--yes`; actual provider usage determines the final charge. Check the balance with `GET /api/v1/credits`, `animaguru credits`, or `get_project` over MCP. Never resubmit a paid job to check on it; poll the job instead. ## Agent skills `animaguru init` writes the AnimaGuru skill to `.agents/skills/animaguru/SKILL.md` in your project, and `animaguru create` adds a skill for each animation style. The skill explains project selection, credit authorization, generation, waiting for jobs and exporting assets. [The agent skills index](https://animaguru.com/.well-known/agent-skills/index.json) lists the published skills: one for MCP clients and one for the CLI. The ChatGPT plugin bundles MCP and CLI guidance plus PixiJS v8 skills. Its directory release is coming soon while review is in progress. To let an agent handle CLI or MCP setup today, use **Copy setup prompt** on the [agent setup page](https://animaguru.com/agent-setup.md); the prompt ends with a read-only connection check. ## Machine-readable resources - [llms.txt](https://animaguru.com/llms.txt) and [llms-full.txt](https://animaguru.com/llms-full.txt): a map of the site for language models, and the full text of these pages. - Markdown versions of public pages: add `.md` to the path, as in [/docs.md](https://animaguru.com/docs.md) or [/index.md](https://animaguru.com/index.md) for the home page. The home page also answers `Accept: text/markdown`. - [openapi.json](https://animaguru.com/openapi.json) and [the API catalog](https://animaguru.com/.well-known/api-catalog) for the REST API. - [The AI catalog](https://animaguru.com/.well-known/ai-catalog.json) and [the MCP server card](https://animaguru.com/mcp/server-card) for the MCP server. - [auth.md](https://animaguru.com/auth.md) for authentication, and [the agent skills index](https://animaguru.com/.well-known/agent-skills/index.json). - [The sitemap](https://animaguru.com/sitemap.xml). ## Help Email hello@animaguru.com or visit [support](https://animaguru.com/support.md). Include the time of the error and the tool or endpoint name. Never send passwords or access tokens.