MCP — gunni.ai docs

What is MCP

MCP (Model Context Protocol) is an open standard that lets AI assistants call external tools in a structured way. When you connect Gunni via MCP, your AI client (Claude Desktop, Cursor, Claude Code) gains the ability to generate images, video, audio, and more directly in conversation. No copy-pasting URLs or switching windows.

Gunni exposes its full toolset through an MCP server hosted at https://api.gunni.ai/mcp. Any MCP-compatible client can connect using HTTP transport with your API key for authentication.

Claude Desktop Setup

Claude Desktop supports adding MCP servers directly from the UI. No config files needed.

Open Claude Desktop settings and go to the MCP section.

Click Add MCP Server. Name it Gunni.

Enter the server URL:

https://api.gunni.ai/mcp

Claude will open an authorization page. Sign in with your Gunni account to grant access.

After authorizing, you'll be redirected back to Claude Desktop. Gunni tools will appear in the tool picker (the hammer icon).

Cursor Setup

Add the same configuration to your Cursor MCP settings. Open Cursor settings, navigate to the MCP section, and add the Gunni server:

{
  "mcpServers": {
    "gunni": {
      "type": "http",
      "url": "https://api.gunni.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Claude Code Setup

Run this command in your terminal to add Gunni as an MCP server:

claude mcp add --transport http gunni https://api.gunni.ai/mcp

Claude Code will handle authentication via OAuth. You can also add it manually by creating a .mcp.json file in your project root:

{
  "mcpServers": {
    "gunni": {
      "type": "http",
      "url": "https://api.gunni.ai/mcp"
    }
  }
}

OpenClaw Setup

Gunni is available as an AgentSkill on ClawHub, the OpenClaw skill registry.

clawhub install gunni

Set your GUNNI_API_KEY in your OpenClaw environment config or .env file:

GUNNI_API_KEY=your_key_here

After installation, the agent can call Gunni skills through natural conversation. No additional per-call setup required.

Generation Tools

These tools create media and consume credits.

image

Generate, edit, upscale, describe, or remove the background from an image. Auto-routes based on the combination of parameters provided.

Name	Type	Default	Description
prompt	string	—	Text prompt for generation or editing. Optional if using upscale, remove_bg, or describe.
image	string \| string[]	—	Input image URL(s). Triggers edit, describe, upscale, or remove_bg mode.
model	string	—	Override the default model for this operation.
output	string	—	Output file path (CLI) or filename hint (MCP).
width	number	—	Output width in pixels.
height	number	—	Output height in pixels.
seed	number	—	Seed for reproducible results.
upscale	boolean	—	Upscale the input image.
remove_bg	boolean	—	Remove the background from the input image.
scale	number	2	Upscale factor. Accepts 2 or 4.
variants	number	1	Number of variants to generate.
style	string	—	Apply a saved visual style by name.
preset	string	—	Apply a saved production preset by name.

video

Generate video from a still image or text prompt.

Name	Type	Default	Description
image	string	—	Input image URL for image-to-video mode.
prompt	string	—	Text prompt describing the desired motion or scene.
model	string	—	Override the default video model.
output	string	—	Output file path or filename hint.
duration	number	—	Video duration in seconds (typically 5 or 10).
style	string	—	Apply a saved visual style by name.
preset	string	—	Apply a saved production preset by name.

audio

Convert text to natural-sounding speech.

Name	Type	Default	Description
text	string	—	The text to synthesize into speech.
model	string	minimax-speech	TTS model to use.
output	string	—	Output file path or filename hint.
voice	string	—	Voice ID or name (model-dependent).

lipsync

Lip synchronization: sync audio to a video, or animate an image to speak.

Name	Type	Default	Description
video	string	—	Input video URL for lip sync mode.
image	string	—	Input image URL for avatar mode.
audio	string	—	Audio URL to sync.
model	string	—	Model to use (kling-lipsync, kling-avatar, sync-lipsync).
output	string	—	Output file path or filename hint.

Knowledge Tools

These tools are free and do not consume credits.

learn

Access the creative knowledge base. Returns guides on prompting, brand design, video production, and more.

Name	Type	Default	Description
topic	string	—	Topic to learn about (e.g. prompting, brand, video).

models

List available models and their capabilities.

Name	Type	Default	Description
category	string	—	Filter by model category (image, video, audio, etc.).
updates	boolean	—	Show recent model updates and additions.

history

Search your past generations.

Name	Type	Default	Description
query	string	—	Search query to filter results.
limit	number	20	Maximum number of results to return.

visual_research

Search for reference images and visual inspiration.

Name	Type	Default	Description
query	string	—	Search query for visual research.
num	number	6	Number of results to return (max 20).

Asset Management Tools

These tools manage your saved assets: reference images, styles, presets, templates, and pipelines. All are free and do not consume credits.

refs

Look up reference images stored in your collections.

Name	Type	Default	Description
name	string	—	Name of a specific reference to retrieve.
collection	string	—	Filter by collection name.
list_collections	boolean	—	List all collections.

ref_save

Save a reference image by URL.

Name	Type	Default	Description
url	string	—	URL of the image to save.
name	string	—	Name for the reference.
description	string	—	Optional description.
collection	string	—	Collection to save into.

upload_ref

Upload a local reference image (triggers a signed URL upload flow).

Name	Type	Default	Description
name	string	—	Name for the reference.
description	string	—	Optional description.
collection	string	—	Collection to save into.

styles

List or retrieve visual styles.

Name	Type	Default	Description
name	string	—	Name of a specific style to retrieve.

style_create

Create a new visual style.

Name	Type	Default	Description
name	string	—	Unique style identifier.
display_name	string	—	Human-readable display name.
description	string	—	Description of the visual direction.
direction	string	—	Detailed creative direction text.
negative	string	—	Negative prompt (things to avoid).
model_pref	string	—	Preferred model for this style.
ref_ids	string[]	—	Reference image IDs to attach.

style_delete

Delete a visual style.

Name	Type	Default	Description
name	string	—	Name of the style to delete.

presets

List or retrieve production presets.

Name	Type	Default	Description
name	string	—	Name of a specific preset.
platform	string	—	Filter by platform (instagram, tiktok, web, etc.).

preset_create

Create a production preset.

Name	Type	Default	Description
name	string	—	Unique preset identifier.
display_name	string	—	Human-readable display name.
platform	string	—	Target platform.
aspect_ratio	string	—	Output aspect ratio (e.g. 1:1, 16:9, 9:16).
framing_rules	string	—	Framing and composition rules.
prompt_suffix	string	—	Text appended to every prompt.
prompt_avoid	string	—	Text to avoid in generations.
voice_ref	string	—	Voice reference for audio.
character_ref	string	—	Character reference image.
style_ref	string	—	Style reference.
model_pref	string	—	Preferred model.
published	boolean	—	Whether the preset is publicly visible.

preset_delete

Delete a production preset.

Name	Type	Default	Description
name	string	—	Name of the preset to delete.

templates

List or retrieve prompt templates.

Name	Type	Default	Description
name	string	—	Name of a specific template.
category	string	—	Filter by category.
tool	string	—	Filter by tool (image, video, audio).

template_save

Create or update a prompt template.

Name	Type	Default	Description
name	string	—	Unique template identifier.
display_name	string	—	Human-readable display name.
category	string	—	Template category.
prompt	string	—	The prompt template text (supports variables).
tool	string	—	Target tool (image, video, audio).
model	string	—	Recommended model.
variables	string	—	Comma-separated list of template variables.
notes	string	—	Usage notes.
published	boolean	—	Whether the template is publicly visible.

template_delete

Delete a prompt template.

Name	Type	Default	Description
name	string	—	Name of the template to delete.

pipelines

List or retrieve multi-step workflows.

Name	Type	Default	Description
name	string	—	Name of a specific pipeline.

pipeline_save

Create or update a multi-step pipeline.

Name	Type	Default	Description
name	string	—	Unique pipeline identifier.
display_name	string	—	Human-readable display name.
description	string	—	Pipeline description.
preset	string	—	Default preset to apply.
intake	JSON	—	Input schema definition.
steps	JSON	—	Array of pipeline step definitions.
published	boolean	—	Whether the pipeline is publicly visible.

pipeline_delete

Delete a pipeline.

Name	Type	Default	Description
name	string	—	Name of the pipeline to delete.

Image Tool Routing

The image tool automatically selects the right operation based on the combination of parameters you provide. No need to call separate tools for generate, edit, describe, upscale, or background removal.

Input	Operation	Default Model
prompt only	Generate a new image	nano-banana
image + prompt	Edit the image using the prompt	nano-banana-edit
image only	Describe the image	florence-2
image + upscale: true	Upscale the image	topaz-upscale
image + remove_bg: true	Remove background	bria-bg-remove