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

# MCP server

> Connect Codex, Claude Code, Cursor, VS Code or any MCP client to every SnapGen model through the hosted MCP server at api.snapgen.org/mcp.

SnapGen runs a hosted [Model Context Protocol](https://modelcontextprotocol.io)
server. Once it is connected, an AI agent can search the live model catalog,
read each model's input schema and public price, run chat, image and video
models, and keep checking long jobs, without you writing API requests.

|                   |                                             |
| ----------------- | ------------------------------------------- |
| Endpoint          | `https://api.snapgen.org/mcp`               |
| Transport         | Streamable HTTP, stateless (JSON responses) |
| Authentication    | `Authorization: Bearer $SNAPGEN_API_KEY`    |
| Protocol versions | `2025-06-18`, `2025-03-26`, `2024-11-05`    |

Initialization, tool discovery, catalog search, schemas and pricing work without
a key. Chat, model runs, job checks and the account tool need a valid API key.

## 1. Create an API key

Create a key on the [API keys page](https://snapgen.org/apikeys) and keep it in
an environment variable. Never paste a real key into a shared config file,
screenshot or prompt.

```bash macOS / Linux theme={null}
export SNAPGEN_API_KEY="your_api_key"
```

```powershell Windows PowerShell theme={null}
$env:SNAPGEN_API_KEY="your_api_key"
```

Start your client from the same terminal session so it inherits the variable.

## 2. Add the server to your client

If a config file already lists other MCP servers, add only the `snapgen` entry
and keep the rest.

<Tabs>
  <Tab title="Codex">
    Open Codex settings > MCP servers > Add server > Streamable HTTP, or add
    this to `~/.codex/config.toml`:

    ```toml ~/.codex/config.toml theme={null}
    [mcp_servers.snapgen]
    url = "https://api.snapgen.org/mcp"
    bearer_token_env_var = "SNAPGEN_API_KEY"
    tool_timeout_sec = 45
    ```

    Start a new Codex session to load it.
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http snapgen https://api.snapgen.org/mcp \
      --header "Authorization: Bearer ${SNAPGEN_API_KEY}"
    ```

    Or commit a project-scoped `.mcp.json` (the variable is expanded at load time):

    ```json .mcp.json theme={null}
    {
      "mcpServers": {
        "snapgen": {
          "type": "http",
          "url": "https://api.snapgen.org/mcp",
          "headers": { "Authorization": "Bearer ${SNAPGEN_API_KEY}" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Cursor">
    ```json ~/.cursor/mcp.json theme={null}
    {
      "mcpServers": {
        "snapgen": {
          "url": "https://api.snapgen.org/mcp",
          "headers": { "Authorization": "Bearer ${env:SNAPGEN_API_KEY}" }
        }
      }
    }
    ```

    Use `.cursor/mcp.json` in a project instead to scope it to that repository.
  </Tab>

  <Tab title="VS Code">
    ```json .vscode/mcp.json theme={null}
    {
      "inputs": [
        {
          "type": "promptString",
          "id": "snapgen-key",
          "description": "SnapGen API key",
          "password": true
        }
      ],
      "servers": {
        "snapgen": {
          "type": "http",
          "url": "https://api.snapgen.org/mcp",
          "headers": { "Authorization": "Bearer ${input:snapgen-key}" }
        }
      }
    }
    ```

    VS Code asks for the key once and stores it securely.
  </Tab>

  <Tab title="Other clients">
    Point any client that supports Streamable HTTP at
    `https://api.snapgen.org/mcp` and send the header
    `Authorization: Bearer <your key>`. The server is stateless: it does not
    issue an `Mcp-Session-Id`, and `GET /mcp` answers `405`.

    Clients that can only launch local (stdio) servers can run the
    `@snapgen/mcp` bridge instead. It forwards every call to the same endpoint
    and needs Node.js 20 or newer:

    ```json theme={null}
    {
      "mcpServers": {
        "snapgen": {
          "command": "npx",
          "args": ["-y", "@snapgen/mcp"],
          "env": { "SNAPGEN_API_KEY": "your_api_key" }
        }
      }
    }
    ```

    Add `--categories video,image` or `--models <id>,<id>` to `args` for the
    scoped tool modes described below.
  </Tab>
</Tabs>

## 3. Verify without paying

Ask your agent:

```text theme={null}
Use the SnapGen MCP tools. Confirm the tools are loaded, call snapgen_account,
then search for image-to-video models and read the schema and pricing of one.
Do not run any paid model.
```

You are connected when the SnapGen tools appear, `snapgen_account` returns your
balance, and `snapgen_search_models` returns models. None of these steps
charges your balance.

## Tools

The default address exposes eight compact tools. The agent searches first and
reads a model's schema only when it needs it, which keeps the tool list small.

| Tool                       | Key | What it does                                               |
| -------------------------- | --- | ---------------------------------------------------------- |
| `snapgen_search_models`    | No  | Search the live catalog by task, family or id, with prices |
| `snapgen_get_model_schema` | No  | Input schema, defaults, protocols and an example request   |
| `snapgen_get_pricing`      | No  | Current public price and billing notes                     |
| `snapgen_chat`             | Yes | Run a text model with chat messages                        |
| `snapgen_run_model`        | Yes | Run an image or video model and wait up to 40 seconds      |
| `snapgen_submit_job`       | Yes | Submit a long job and return its `task_id`                 |
| `snapgen_check_job`        | Yes | Status, progress, outputs and charge for a `task_id`       |
| `snapgen_account`          | Yes | Available balance in USD                                   |

When a job is still running, `snapgen_run_model` returns its `task_id`. Keep
checking it with `snapgen_check_job`; submitting the same job again would run
and bill it twice. Pass an `idempotency_key` to make a retried submission safe.

### Scoped tool modes

For stable workflows you can expose one typed tool per model instead:

| Mode                | Address                                                           | Tools                                                  |
| ------------------- | ----------------------------------------------------------------- | ------------------------------------------------------ |
| Automatic discovery | `https://api.snapgen.org/mcp`                                     | The eight compact tools                                |
| By category         | `https://api.snapgen.org/mcp?categories=video,image`              | One `run_<model>` tool per model in up to 3 categories |
| Specific models     | `https://api.snapgen.org/mcp?models=seedance-2.0-t2v,gpt-image-2` | One `run_<model>` tool for each of up to 20 models     |

Scoped modes also keep `snapgen_check_job` and `snapgen_account`. Each typed
tool's input schema is the model's live request schema, plus `wait_seconds`
and `idempotency_key` for media models.

## Billing

MCP does not change prices. Every model call is an ordinary API request made
with your key: the same prices, balance, key limits and model allowlist apply,
and failed generations are not charged. Searching, reading schemas and reading
prices are free.

## Troubleshooting

* **No SnapGen tools:** check where the config was saved, then reload the MCP
  server or restart the client.
* **"This tool needs an API key":** the client is not sending the
  `Authorization` header. Make sure `SNAPGEN_API_KEY` is set in the environment
  that starts the client.
* **401 or 403 from a paid tool:** the key is invalid, revoked, or not allowed
  to use that model. Check it on the API keys page.
* **Tool timeouts:** use `snapgen_submit_job` for video and poll with
  `snapgen_check_job` instead of waiting in one call.