Codex Pets MCP server
Commit Nov 13, 2026Allows an AI client to generate, inspect, and share animated Codex-compatible pets using text prompts and YDB-backed asset storage.
Also known as astandrik/codex-pets
- Stars
- 3
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- Apache-2.0
What is Codex Pets MCP?
Codex Pets allows an AI client to generate, inspect, and share animated Codex-compatible pets using text prompts and YDB-backed asset storage.
Summary generated from the project's README
About Codex Pets MCP server
Creating and managing animated digital companions for AI coding agents is what codex-pets enables. Developers can use text prompts to generate unique, Codex-compatible pets that include animation states and multiple look directions. The server handles the complex generation process, providing assets like pet.json, spritesheet.webp, and pet.zip files once a task is complete.
This remote MCP server connects to a centralized system using YDB-backed storage for assets and local accounts for user management. Users interact with the service by providing a text prompt up to 2000 characters and a unique requestId to ensure idempotency. Once generated, pets can be inspected or submitted to a public community gallery for sharing. The system manages a global queue and specific daily quotas to regulate generation tasks, ensuring that assets are stored securely as binary blobs until they are approved for public viewing.
What you can do with it
- 1Generate animated pets from textAn AI client can create a new animated pet by sending a text prompt and a unique request ID.
- 2Monitor generation progressDevelopers can poll the status of a pet generation task to receive download links for the final assets.
- 3Submit pets to a galleryUsers can move their private pet creations into a public community gallery for others to see.
- 4Install pet packs via CLICoding agents can quickly integrate approved pet collections into their environment using a command line tool.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
AUTH_MODEAUTH_SINGLE_USER_EMAILAUTH_SINGLE_USER_IDAUTH_SINGLE_USER_NAMECODEX_PETS_DATA_SOURCEINITIAL_ADMIN_EMAILSNEXT_PUBLIC_APP_URLNEXT_PUBLIC_BASE_PATHPASSWORD_PEPPERSESSION_COOKIE_SECRETYDB_ANONYMOUS_CREDENTIALSYDB_ENDPOINTYDB_PETS_DATABASEYDB_PETS_ENDPOINTYDB_STATIC_CREDENTIALS_AUTH_ENDPOINTYDB_STATIC_CREDENTIALS_PASSWORD_FILEYDB_STATIC_CREDENTIALS_USER
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableastandrik/codex-pets is public and reachablegithub.com/astandrik/codex-pets ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/astandrik/codex-pets ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubCodex Pets
Community gallery for Codex-compatible animated pets with local accounts, manual moderation, public generation requests, YDB-backed asset storage, and public detail pages for approved and pending pets.
Public site: https://pets.ydb-qdrant.tech/.
My generations in this browser
/my-generations lists tasks accepted here and available private results explicitly
opened in the same browser, without signing in. Each entry stores only its private
capability ID and saved/expiry timestamps in browser storage. Descriptions and
images are not stored in this history. Keep browser data and private links safe;
anyone with access to either can open the corresponding result.
Statuses use the existing per-generation GET endpoint, with at most three reads at once. Live tasks refresh; ready/failed tasks stop polling. This view never creates, retries, cancels or publishes a task. Results still expire 24 hours after acceptance. History retains the latest 50 entries for seven days after expiry; expired entries cannot be opened. Clearing browser data removes this list, but does not reset quotas or cancel tasks. Earlier unknown links cannot be recovered; opening an existing available private link adds it to this browser's list.
The history, form and result pages exclude analytics and search indexing. History has private/no-store and no-referrer headers. There is no IP-based ownership lookup, account synchronization, server-side history enumeration or new database schema.
Generate a pet through remote MCP
generate_pet accepts a text prompt (1–2000 characters), optional displayName (up to 80 characters), and a fresh random UUID requestId. Reuse that requestId with identical content after a disconnected response: no duplicate task or extra quota. Changed content with the same ID is rejected. Keep request and generation IDs private.
Poll get_pet_generation(generationId) every 5 seconds. A completed job returns an unlisted preview and downloads: pet.json, lossless spritesheet.webp, and pet.zip. Format v2 is 1536×2288 with 9 animation states and 16 look directions. Results expire 24 hours after acceptance; idempotency hashes remain 7 days. Completed new tasks include editable name/description/tags. The private preview saves description changes atomically into pet.json and ZIP; tags are stored for the gallery submission. Saving is free of provider calls, keeps the sprite bytes unchanged, requires the current metadata revision and is disabled after submission. Existing completed tasks can be edited manually without a new model call. An unavailable or unknown metadata response leaves a usable image package and manual fields; it is never retried automatically, and unknown charges retain an accounting marker. The tool never publishes into the gallery. Before expiry, use Submit for review on the private result page to save a permanent gallery package and one pending submission, or upload the ZIP through /submit. Submission retries return the same receipt, including after a lost response. Anyone holding the private link can submit that result once; if signed in, the first submitter owns the submission. Contacts stay private. Submitting the saved package makes no generation-provider calls and does not change generation quotas. Later approval can prepare metadata and search embeddings through the existing admin workflow.
The operator funds twelve GPT Image 2.6 Sunburst/high stages per task through sprite-gen 2.44.0: one base and eleven rows. After the base, up to eleven rows run concurrently. By default, each failed image stage can receive one retry after five seconds for RemoteDisconnected, IncompleteRead, HTTP 500 or HTTP 520 (at most 24 image calls). With PET_GENERATION_ANIMATION_AUTO_REPAIR_ENABLED=true, newly admitted tasks also repair diagnosed animation-quality failures: at most four image calls per animation row, including the first call, transport retries and confirmed output-moderation retries. Base keeps its two-call limit, so a full task can use at most 46 image calls. Retries use the existing recorded-spend budget, keep the same task/quota/24-hour expiry, and persist their tokens and counters across worker restarts. Ambiguous started calls are not replayed. Tasks without a saved automatic-repair policy retain legacy limits; terminal tasks are not restarted and free rebuilds never trigger paid repair. Only failed or diagnosed-invalid rows are regenerated; successful sibling rows are kept. New tasks then make at most one gpt-6.1-sol text/vision request to draft an English name, description and tags; metadata is not retried automatically.
All future image calls use gpt-image-2.6-sunburst, including remaining stages and allowed retries of older tasks. Existing images and recorded attempts are retained. A model change never replays an unknown request or creates a new attempt by itself. See the model rollout procedure.
Output-moderation retries require provider_rejected, HTTP 400, moderation_blocked and an explicit moderationStage=output. They send the same prompt, reference images and model/settings through the unchanged provider safety checks. Input/unknown-stage blocks, other rejection codes and records without that provenance remain terminal. A refused output without usage retains an unknown-cost marker. This is an explicit bounded application policy, not a guarantee that another result will pass; OpenAI recommends revising moderation-blocked requests instead of automatically repeating them.
With PET_GENERATION_REVIEW_FLOW_ENABLED=true, the website accepts a character image, text, or both and pauses after the base character for explicit user confirmation. The flag defaults to false. Confirmation resumes the same task without another daily attempt; JSON and MCP admissions remain automatic regardless of the flag; existing jobs retain their saved policy. Before confirmation, Edit character creates a new text-guided version from the saved base, using one ordinary attempt while preserving the previous version. References remain private and expire with the job. See website review and image references for limits and rollout requirements.
PET_GENERATION_BASE_RETRY_ENABLED=true enables the website's explicit retry for a failed base character and retains its accepted input privately until the original 24-hour expiry. The default is false. A retry creates one new review task per source and consumes one ordinary daily attempt under the existing shared budget; it does not extend or re-open the source. UUID replay, concurrent tabs and source-pointer recovery return the same child. Legacy tasks require an explicit image-only choice or re-entered description; a corrupt new snapshot never becomes legacy input. For legacy sources, only confirmed output-moderation refusals, HTTP429 refusals and unstarted queue timeouts qualify. A source with an exhausted explicit baseRepair journal also qualifies when every attempt records an eligible failure, including supported transport failures. Uncertain outcomes stay blocked. The retry dialog supports 0–50 additional automatic base retries (default 5 when the server advertises support): 0 means one base attempt, 5 means at most six. Eligible transport, rate-limit, and confirmed output-moderation failures share this limit; success stops at character review and never starts animations automatically. One accepted child consumes one daily quota attempt, while each provider call contributes to spending and the existing budget guard. Initial generation and animation policy are unchanged. Requests omitting the setting retain the legacy policy.
Base-retry recovery keeps the original pets-base-retry-v1:<sourceId> identity format. A separate pets-base-retry-settings-v1:<sourceId>:<requestId> entry stores only the submitted retry count (or explicit legacy omission), never descriptions or images. After an uncertain response, check the receipt before resending. If settings are missing, explicitly restore the original count or select the legacy-omission checkbox; legacy descriptions must be re-entered exactly. A different request cannot silently replace a pending operation.
The website form at /generate and remote MCP share one queue. Limits are 2000 accepted tasks/day globally and 100/IP by default (configurable via PET_GENERATION_DAILY_GLOBAL_LIMIT and PET_GENERATION_DAILY_IP_LIMIT), one active task and 30 waiting by default (PET_GENERATION_QUEUE_LIMIT, integer 1–200, must match in web and worker), counted by Moscow calendar day. Waiting alone does not cancel queued tasks; their original 24-hour lifetime still applies. Accepted tasks consume quota even if they expire or fail. An explicitly activated scheduler v2 supports two active tasks with a shared provider-call cap of 11 by default (1–22); scheduler v3 leases individual base/animation tasks and shares a 20-default (1–22) pool across processes. Retry waits release their slot. See task pool rollout for explicit activation. Fully recorded terminal provider failures are isolated to their failed task; unconfirmed writes, lost leases and unclassified outcomes pause further paid work for operator review. No monetary threshold applies by default (PET_GENERATION_BUDGET_USD unset, empty or 0); cost accounting remains enabled. A positive finite value enables an optional daily recorded-spend threshold without monetary reservations. In-flight calls and unknown charges can exceed an enabled threshold; unknown-cost markers remain across task expiry and midnight. The prompt form and private previews exclude analytics/Webvisor. See row recovery and accounting for the operational contract.
Generation is disabled by default and available through the website form and remote MCP. The npm CLI and browser WebMCP retain their catalog-only tools. See DEPLOYMENT.md for explicit schema, candidate and manual-enable steps.
Stack
- Next.js 16 App Router, React 19, TypeScript strict
- Gravity UI + SCSS/BEM
- local-ydb / YDB native gRPC via
ydb-sdk - App-owned email+password auth with YDB-backed users and sessions
- Pet assets stored in YDB as binary blobs
- Dynamic
robots.txt,sitemap.xml,llms.txt,llms-full.txt, and OpenAPI JSON - Agent-facing HTTP access through
llms.txt/llm.txt,/llms-full.txt,/mcp, JSON routes, and TOON mirrors for core registry data - Optional read-only browser WebMCP tools in supported browser runtimes
- Yandex Metrika using the same counter as
ydb-qdrant-ui(104844437), with optional server-side aggregate MCP metrics - JSZip + Sharp for package validation
Development
nvm use 24
npm install
cp .env.example .env.local
npm run dev
Open http://localhost:3000.
Run the local checks before submitting changes:
npm run lint
npx tsc --noEmit --incremental false
npm test
CODEX_PETS_DATA_SOURCE=mock NEXT_TELEMETRY_DISABLED=1 npm run build
Agent access
Codex Pets exposes a public MCP server so coding agents can search, inspect, install, and share approved pet packs.
Primary public surfaces:
- Best guide: https://pets.ydb-qdrant.tech/guides/best-codex-pets-for-ai-coding-agents
- LLM discovery: https://pets.ydb-qdrant.tech/llms.txt
- MCP endpoint: https://pets.ydb-qdrant.tech/mcp
- Public manifest: https://pets.ydb-qdrant.tech/api/manifest
- CLI install:
npx @astandrik/codex-pets install <slug>
Connect Codex:
codex mcp add codexPets --url https://pets.ydb-qdrant.tech/mcp
Run a local stdio MCP server that proxies the public gallery:
npx @astandrik/codex-pets mcp
Available MCP tools:
search_pets— discover approved pets when you need candidates or lack an exact slugget_pet— fetch one public pet card when you already have an approved slugget_install_instructions— get install commands without incrementing metricsget_badge_code— generate README badge snippets for a known slugget_embed_code— generate iframe embed snippets for a known slugget_card_code— generate animated GIF snippets for a known slug, defaulting to sprite-only modeget_pet_request_info— discover the public new-pet request workflow; it does not submit or inspect private requests
HTTP fallback routes are public too:
/openapi.json/api/openapi.json/llms-full.txt/guides/best-codex-pets-for-ai-coding-agents/guides/best-codex-pets-for-ai-coding-agents.md/api/manifest/api/manifest.toon/api/pets/api/pets.toon/api/pets/<slug>/api/pets/<slug>.toon/pets/<slug>/markdown/api/tags/api/tags.toon/api/pets/<slug>/share/badge/<slug>.svg/card/<slug>.gif/embed/<slug>
The crawlable HTML gallery lives on /; numbered pages use /?page=2,
/?page=3, and so on. The legacy /pets catalog URL permanently redirects
to the equivalent homepage URL, while pet details remain on /pets/<slug>.
/api/pets and /api/pets.toon accept optional page and pageSize
parameters and always return pagination metadata. Without either parameter,
the response is page 1 with up to 200 pets. With page but no pageSize, the
page size remains 24. Top-level total is the number of returned pets;
pagination.totalItems is the full filtered count and pagination.hasNextPage
indicates whether more results are available. For the next request, increment
pagination.page and pass the returned pagination.pageSize explicitly.
If you deploy under a subpath such as /codex-pets, set:
NEXT_PUBLIC_BASE_PATH=/codex-pets
NEXT_PUBLIC_APP_URL=https://example.com/codex-pets
The public gallery renders without secrets. For account login, submit, moderation,
and metrics you need YDB_PETS_ENDPOINT, YDB_PETS_DATABASE, and auth env.
Optional server-side MCP metrics also need YANDEX_METRIKA_MP_TOKEN and
YANDEX_METRIKA_MP_CLIENT_ID.
Optional IndexNow notifications are enabled by INDEXNOW_KEY; the app serves
/<key>.txt and pings IndexNow after an admin approves a pet.
Optional semantic search uses Yandex AI Studio text embeddings and exact cosine
ranking in YDB. Query mode defaults to PET_SEARCH_MODE=lexical; shadow
computes semantic ranking without changing public order, and hybrid combines
lexical and text-semantic ranks. An independent
PET_SEARCH_VISUAL_MODE=off|shadow|hybrid adds an offline visual-caption rank
from four fixed sprite frames. Captions and their provenance remain internal;
public JSON, TOON, homepage, MCP, and WebMCP shapes do not change. Configure
YANDEX_AI_STUDIO_FOLDER_ID,
YANDEX_AI_STUDIO_API_KEY_FILE, and
PET_SEARCH_MODEL_REVISION=yandex-text-embeddings-v2-768-2026-07. The v2
runtime uses the managed text-embeddings-v2-doc/query models at 768
dimensions. Set
PET_SEARCH_VISUAL_MODEL_REVISION=yandex-text-embeddings-v2-768-pet-vision-qwen3.6-v1
for the compatible Qwen visual rank. Legacy 256-dimensional revisions remain
registered for rollback. The API key is accepted only through the secret-file
setting. Provider failures and timeouts fall back to lexical results;
visual-only failures preserve the text-hybrid order.
To run without YDB on generated sample data:
CODEX_PETS_DATA_SOURCE=mock AUTH_MODE=single-user \
AUTH_SINGLE_USER_EMAIL=local-admin@example.com \
NEXT_PUBLIC_APP_URL=http://localhost:3000 \
npm run dev -- --port 3000
Production notes
For a dedicated public subdomain such as https://pets.example.com, prefer:
NEXT_PUBLIC_APP_URL=https://pets.example.com
NEXT_PUBLIC_BASE_PATH=
If the app container talks to YDB by Docker hostname, for example
grpc://ydb-local:2136, run the app on the same Docker network as the YDB
containers:
docker run --network ydb-net ...
Telegram and similar preview crawlers are handled by lightweight preview routes:
/api/preview/site/api/preview/pets/[slug]
The reverse proxy should rewrite preview-bot requests for / and /pets/<slug>
to those endpoints before proxying to the normal App Router pages. See:
Codex Pets MCP questions
How do I generate a pet using the MCP server?
You can use the generate_pet tool by providing a text prompt, an optional display name, and a unique requestId.
What files are included in a completed pet generation?
A completed job provides an unlisted preview and a download package containing pet.json, a lossless spritesheet.webp, and a pet.zip file.
How long do pet generation results last?
Results expire 24 hours after they are accepted, though idempotency hashes remain for 7 days.