@inliner/mcp-server

MCP server for Inliner.ai — gives AI coding agents live access to your image projects, credits, and generation.

Works with any Model Context Protocol compatible tool: Claude Code, OpenAI Codex CLI, GitHub Copilot, Gemini CLI, Cursor, Windsurf, and more.

Current release: @inliner/mcp-server@1.3.0, with 12 tools, inexpensive automatic routing, explicit model selection (including Grok Imagine Image 2.0), model-facing initialization instructions, and MCP-safe structured results for array-valued API responses.

For automatic activation guidance as well as tools, install the canonical inliner-ai agent skill/plugin. Codex users can install both layers together:

codex plugin marketplace add inliner-ai/agent-skill --ref v1.3.0
codex plugin add inliner-ai@inliner-ai

Install

Claude Code

claude mcp add --transport stdio inliner -- npx -y @inliner/mcp-server --api-key=YOUR_API_KEY

# Or with environment variable
export INLINER_API_KEY=your-key
claude mcp add --transport stdio inliner -- npx -y @inliner/mcp-server

OpenAI Codex CLI

Use Codex's MCP command:

codex mcp add inliner --env INLINER_API_KEY=your-key -- npx -y @inliner/mcp-server

Then verify the server is configured:

codex mcp list

Or add it manually to ~/.codex/config.toml:

[mcp_servers.inliner]
command = "npx"
args = ["-y", "@inliner/mcp-server"]

[mcp_servers.inliner.env]
INLINER_API_KEY = "your-key"
INLINER_DEFAULT_PROJECT = "your-project-namespace"

If you prefer to keep secrets in your shell environment, export them first and forward them from Codex:

[mcp_servers.inliner]
command = "npx"
args = ["-y", "@inliner/mcp-server"]
env_vars = ["INLINER_API_KEY", "INLINER_DEFAULT_PROJECT"]

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "inliner": {
      "command": "npx",
      "args": ["-y", "@inliner/mcp-server"],
      "env": { "INLINER_API_KEY": "your-key" }
    }
  }
}

VS Code / Cursor / Windsurf

Project-specific (Recommended): Create .cursor/mcp.json (or .vscode/mcp.json) in your project root:

{
  "mcpServers": {
    "inliner": {
      "command": "npx",
      "args": ["-y", "@inliner/mcp-server"],
      "env": {
        "INLINER_API_KEY": "your-key",
        "INLINER_DEFAULT_PROJECT": "your-project-namespace"
      }
    }
  }
}

Global setup: Add to Cursor Settings > Features > MCP, or VS Code MCP settings:

{
  "mcpServers": {
    "inliner": {
      "command": "npx",
      "args": ["-y", "@inliner/mcp-server"],
      "env": { "INLINER_API_KEY": "your-key" }
    }
  }
}

Note: Using the env field is recommended over --api-key command-line arguments for better compatibility with MCP clients.

Preferred project behavior:

• If a tool call omits project, the server resolves it in this order:

  1. INLINER_DEFAULT_PROJECT (if set)

  2. account default project

  3. first available project

  4. "default" fallback

• This reduces repetitive "which project?" confirmations in day-to-day usage.

Related MCP server: openai-gpt-image-1-mcp

Agent behavior

The server publishes initialization instructions that tell compatible agents how to select tools:

• Use generate_image for a new asset that will be inserted, shipped, or verified. It generates the image before returning the account-owned CDN URL.

• Use edit_image when an existing source image is identified.

• Use recommend_image_url only for URL naming or planning. It does not generate an image.

• Reuse existing generated URLs directly.

• Never create a project unless the user requests or approves it.

Generation and editing consume the corresponding account credits. Read-only discovery and URL recommendation do not generate an asset.

Generation cost and model controls

generate_image accepts two independent controls:

• mode: "cheap" automatically routes general images to Z-Image Turbo, text/design-heavy images to Qwen Image, and reference-aware requests to Gemini Flash Lite.

• model selects an exact image model. An explicit model always takes priority over mode.

Example cheap request:

{
  "project": "my-project",
  "description": "five professionals collaborating in a modern office",
  "width": 1200,
  "height": 800,
  "format": "jpg",
  "mode": "cheap"
}

Example explicit model request:

{
  "project": "my-project",
  "description": "editorial poster with precise typography",
  "width": 1200,
  "height": 800,
  "format": "png",
  "model": "IMAGE_GEN_QWEN_IMAGE"
}

The inexpensive explicit model codes are IMAGE_GEN_Z_IMAGE_TURBO, IMAGE_GEN_QWEN_IMAGE, and IMAGE_GEN_NANO_BANANA_LITE. For a reference-aware quality/value option, use IMAGE_GEN_GROK_IMAGINE_2 (Grok Imagine Image 2.0 through OpenRouter, using 1K/low by default).

Tools

Resources

Example Interaction

Once installed, ask your AI agent naturally:

"Create a project called 'marketing' for my marketing team"

The agent will use create_project to reserve the namespace, then you can use it for generating images.

"Add a hero image to the landing page for my acme-corp project"

The agent will:

1. Call get_project_details to get your project config

2. Call generate_image with the right namespace and dimensions

3. Output the <img> tag with the correct URL, alt text, and loading attributes

Smart URL behavior:

• The server recommends concise slugs using POST /url/recommend

• Then generates with full prompt context using POST /content/generate and the selected slug

• This preserves rich prompt quality while producing readable/SEO-friendly URL paths

• recommend_image_url responses include the selected slug plus alternatives and explicitly report generated: false

"Generate a happy duck image and save it to ./images/duck.png"

The agent will:

1. Call generate_image with the description, dimensions, and output path

2. Poll until the image is ready (up to 3 minutes)

3. Save the image to the specified file path

4. Return the URL and file path

"Create a hero image for my landing page"

The agent will:

1. Choose dimensions from the layout and call generate_image

2. Poll until the hosted asset is ready

3. Return the URL and file path

"Edit this local photo to remove the background and resize to 400x400"

The agent will:

1. Call edit_image with sourcePath pointing to the local file

2. Upload the file first (if no URL provided)

3. Apply the edit instruction

4. Resize to specified dimensions

5. Save the result

"How many image credits do I have left?"

The agent calls get_usage and reports your remaining credits by type.

API Key

Generate an API key from Account > API Keys in the Inliner dashboard. Only account owners can create and revoke keys.

Pass it via:

• Environment variable (recommended): INLINER_API_KEY — Use the env field in MCP configuration files

• Command-line argument: --api-key=YOUR_KEY — Works for standalone testing, but may have parsing issues with some MCP clients

Links

• Inliner.ai

• Tutorials

• Model Context Protocol