> ## Documentation Index
> Fetch the complete documentation index at: https://docs.littledemo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

Let Claude, Codex, and other AI agents drive LittleDemo through the Model Context Protocol.

The CLI ships an MCP server: `littledemo mcp` speaks the Model Context Protocol
over stdio, exposing LittleDemo as tools any MCP-capable agent can call.

## Setup

```bash
# Claude Code
claude mcp add littledemo --env LITTLEDEMO_API_KEY=ld_live_xxx -- littledemo mcp

# Codex (~/.codex/config.toml)
[mcp_servers.littledemo]
command = "littledemo"
args = ["mcp"]
env = { LITTLEDEMO_API_KEY = "ld_live_xxx" }
```

Authentication is the `LITTLEDEMO_API_KEY` environment variable only — the
server never prompts and never opens a browser. Without a key, every tool call
returns actionable guidance instead of hanging.

## Tools

| Tool | What it does |
|---|---|
| `whoami` | Auth check, plan, remaining quota — agents should call this first |
| `list_projects` / `create_project` | Project discovery and setup |
| `list_demos` / `get_demo` | Inspect demos; poll `get_demo` for async generations |
| `create_demo` | Cloud generation from prompt (blocks until ready by default; `wait: false` to queue) |
| `upload_recording` | Host a local MP4/WebM (≤100 MB) as an instantly-ready demo, with optional thumbnail + GIF attach |
| `get_embed_code` | Copy-paste iframe HTML, GitHub markdown (inline GIF → share page), or bare URLs |

A typical agent flow: `whoami` → `list_projects` → record locally (agents in a
repo can run `littledemo record <url> --json`) → `upload_recording` with the
thumbnail/GIF the recorder produced → `get_embed_code format=markdown` → paste
into a PR comment.

## This repo

`.mcp.json` at the repo root registers the server for Claude Code sessions in
this repository (pointing at the built CLI — run `npm run build:cli` first).
`scripts/test-mcp-smoke.mjs` (part of `test:all`) asserts the handshake, the
8-tool contract, and that stdout stays pure JSON-RPC.