MCP server

SnapGen runs a hosted Model Context Protocol 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, video, music, and dubbing 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. The MCP page on snapgen.org builds the config for your client, including the scoped tool modes.

1. Create an API key

Create a key on the API keys page and keep it in an environment variable. Never paste a real key into a shared config file, screenshot or prompt.

macOS / Linux

export SNAPGEN_API_KEY="your_api_key"

Windows PowerShell

$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.

Codex
Claude Code
Cursor
VS Code
Other clients

Open Codex settings > MCP servers > Add server > Streamable HTTP, or add this to ~/.codex/config.toml:

~/.codex/config.toml

[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.

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):

.mcp.json

{
  "mcpServers": {
    "snapgen": {
      "type": "http",
      "url": "https://api.snapgen.org/mcp",
      "headers": { "Authorization": "Bearer ${SNAPGEN_API_KEY}" }
    }
  }
}

~/.cursor/mcp.json

{
  "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.

.vscode/mcp.json

{
  "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.

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:

{
  "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.

3. Verify without paying

Ask your agent:

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, video, music, or dubbing 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. Speech, transcription, and the other instant audio models return audio bytes in one HTTP response, which MCP can’t carry. Call their endpoints directly, for example Text to speech.

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, music, and dubbing, and poll with snapgen_check_job instead of waiting in one call.

Overview

Agent Tools

Development Tools

SDKs

1. Create an API key

2. Add the server to your client

3. Verify without paying

Tools

Scoped tool modes

Billing

Troubleshooting

​1. Create an API key

​2. Add the server to your client

​3. Verify without paying

​Tools

​Scoped tool modes

​Billing

​Troubleshooting

1. Create an API key

2. Add the server to your client

3. Verify without paying

Tools

Scoped tool modes

Billing

Troubleshooting