LLM Gateway MCP Server

Connect your AI assistant to LLM Gateway to inspect your usage and costs, discover your most-used models, providers and coding apps, and generate text or images. The same API key connects all of these tools.

Connection and discovery

Connect with Streamable HTTP at https://llmgateway.io/mcp or https://api.llmgateway.io/mcp. Send an API key in Authorization: Bearer <api-key>. A GET without an SSE Accept header returns public server information; browser navigation on the main domain opens the setup page.

For protocol requests, POST a single JSON-RPC message with Content-Type: application/json and Accept: application/json, text/event-stream. Initialize first, then send the negotiated MCP-Protocol-Version header on subsequent requests. The transport is stateless: requests return JSON, accepted notifications return an empty 202, and standalone SSE subscriptions and session deletion return 405. Clients using the original HTTP+SSE bridge remain supported.

Protected resource metadata publishes authentication discovery. Unauthorized protocol requests include a WWW-Authenticate challenge pointing to it.

What is MCP?

The Model Context Protocol (MCP) is an open standard that allows AI assistants to connect with external tools and data sources. LLM Gateway's MCP server exposes tools for:

• Account and usage analytics - Check spending limits, request/token totals, costs, trends, and provider/model/app rankings
• Chat completions - Send messages to any supported LLM
• Image generation - Generate images using models like Qwen Image
• Nano Banana image generation - Generate images with Gemini 3 Pro Image and optionally save to disk
• Model discovery - List available models with capabilities and pricing

Available Tools

get-account

Inspect the connected user, organization, project, role, analytics scope, and API key spending limits. Owners and admins also receive the organization's current credit balance. The balance is not a DevPass plan allowance. No parameters are required, and credentials are never returned.

get-usage

Get request/token totals, errors, cache hits, costs, a time series, and your most-used provider, model, and coding agent/app by request count.

{
	"from": "2026-08-01",
	"to": "2026-08-31",
	"granularity": "day"
}

The response includes scope, the resolved dates, updatedAt, totals, series, mostUsedProvider, mostUsedModel, mostUsedApp, and appUsageCoverage. Only time buckets with activity appear in series. Empty periods return zero totals, an empty series, and null rankings.

get-usage-breakdown

Rank providers, models, coding apps, or API keys by requests, inference cost, or tokens.

{
	"group_by": "app",
	"sort_by": "cost",
	"limit": 10
}

The response includes each row's ID, display name, requests, tokens and costs, plus pagination.hasMore and coverage. Increase offset by limit to get the next page. Known app aliases are combined before ranking. unknown identifies requests with no recorded source; custom app names remain as recorded.

Analytics scope and cost fields

• Owners and admins see the connected project's usage across its keys. Developers see only the keys they created in that project, including inactive-key history.
• A project API key does not grant access to another project or organization. Tools do not accept scope overrides. Use a key for the project you want to inspect.
• Use an active user API key. Customer credentials and expired or revoked keys cannot read account analytics. Project access is checked on every analytics request.
• Analytics tools are read-only, incur no model charges, and remain available when a key or member reaches a spending limit. Generation tools still enforce those limits.
• costUsd is inference usage cost. creditsCostUsd and byokCostUsd separate gateway credits from provider costs paid with your own provider keys. dataStorageCostUsd is separate. These are usage statistics, not invoice totals or exact changes in credit balance.
• Statistics come from hourly aggregates, survive request-retention cleanup, and may lag recent requests. updatedAt reports the last summary aggregation in the requested period.
• App attribution uses the request's recorded source, including recognized coding clients and x-source values. MCP generation calls preserve client attribution headers. Configure x-source on your MCP connection if your client does not identify itself. Attribution does not identify which person used a shared key.
• Historical per-key app statistics start when per-key source aggregation is enabled. appUsageCoverage / coverage compare recorded breakdown requests with total requests; complete: false means rankings cover only part of the period. This differs from an unknown source, which is a recorded request without app attribution.

All three tools return JSON in both structuredContent and a text content block for older clients. An unavailable backend produces a tool error, never a fabricated zero-usage report.

chat

Send a message to any LLM and get a response.

Parameters:

• model (string) - A model ID from list-models or the live catalog
• messages (array) - Array of messages with role and content
• temperature (number, optional) - Sampling temperature (0-2)
• max_tokens (number, optional) - Maximum tokens to generate

Example:

{
	"model": "MODEL_ID",
	"messages": [{ "role": "user", "content": "Explain quantum computing" }],
	"temperature": 0.7
}

generate-image

Generate images from text prompts using AI image models.

Parameters:

• prompt (string) - Text description of the image to generate
• model (string, optional) - Image model (default: "qwen-image-plus")
• size (string, optional) - Image size (default: "1024x1024")
• n (number, optional) - Number of images (1-4, default: 1)

Example:

{
	"prompt": "A serene mountain landscape at sunset",
	"model": "qwen-image-max",
	"size": "1024x1024"
}

generate-nano-banana

Generate an image using Gemini 3 Pro Image ("Nano Banana Pro"). Returns an inline image preview, and optionally saves the image to disk when the server is configured with an upload directory.

Parameters:

• prompt (string) - Text description of the image to generate
• filename (string, optional) - Filename for the saved image, no path separators allowed (default: nano-banana-{timestamp}.png)
• aspect_ratio (string, optional) - Aspect ratio: "1:1", "16:9", "4:3", or "5:4"

Example:

{
	"prompt": "A pixel-art cat sitting on a rainbow",
	"filename": "hero-image.png",
	"aspect_ratio": "16:9"
}

list-models

List available LLM models with capabilities and pricing.

Parameters:

• include_deactivated (boolean, optional) - Include deactivated models
• exclude_deprecated (boolean, optional) - Exclude deprecated models
• limit (number, optional) - Maximum models to return (default: 20)
• family (string, optional) - Filter by model family

list-image-models

List all available image generation models.

Use the tool for current model IDs, capabilities, and pricing, or browse the live models page.

Setup

claude mcp add --transport http --scope user llmgateway https://api.llmgateway.io/mcp \
  --header "Authorization: Bearer your-api-key-here"

{
  "mcpServers": {
    "llmgateway": {
      "url": "https://api.llmgateway.io/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

codex mcp add llmgateway --url https://api.llmgateway.io/mcp \
  --bearer-token-env-var LLM_GATEWAY_API_KEY

[mcp_servers.llmgateway]
url = "https://api.llmgateway.io/mcp"
bearer_token_env_var = "LLM_GATEWAY_API_KEY"

{
  "mcpServers": {
    "llmgateway": {
      "url": "https://api.llmgateway.io/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

curl -X POST https://api.llmgateway.io/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

curl -N https://api.llmgateway.io/mcp \
  -H "Accept: text/event-stream" \
  -H "Authorization: Bearer your-api-key"

Use Cases

Usage and Spending

What did I spend this month, and which coding app accounts for the most cost?
Show my most-used model and provider, then compare daily usage with last month.

Use get-account to confirm the scope, get-usage for each period, and get-usage-breakdown with group_by: "app" and sort_by: "cost" for the app ranking.

Multi-Model Access in Claude Code

Use Claude Code to interact with models it doesn't natively support:

List available models, then use the chat tool with a suitable model to review this code.

Image Generation

Generate images directly from your AI assistant:

Use generate-image to create a logo for my new startup.
It should be minimalist, blue and white, representing AI and cloud computing.

Nano Banana (Gemini Image Generation)

Generate images with Gemini 3 Pro for use in your project:

Use generate-nano-banana to create a hero image for my landing page with a 16:9 aspect ratio.

Cost-Effective Model Selection

Query available models to find the best option for your task:

List models and their pricing, then choose a suitable low-cost model for this task.

Authentication

The MCP server supports two authentication methods:

1. Bearer Token - Authorization: Bearer your-api-key
2. API Key Header - x-api-key: your-api-key

Use the same project API key you use for inference. Analytics access follows the scope rules above.

OAuth Support

For applications that prefer OAuth authentication, LLM Gateway's MCP server implements OAuth 2.0:

• Authorization Endpoint: /oauth/authorize
• Token Endpoint: /oauth/token
• Registration Endpoint: /oauth/register
• Supported Flows: Authorization Code, Client Credentials

Enabling Local Image Saving

By default, generate-nano-banana returns images inline without writing to disk. To enable saving generated images to the server filesystem, the UPLOAD_DIR environment variable must be set on the gateway host at startup. This is a server-side setting — it cannot be configured from the client.

This is only possible for self-hosted MCP deployments. Configure UPLOAD_DIR using your deployment method:

• Docker: Pass -e UPLOAD_DIR=/data/images or add it to your docker-compose.yml environment section.
• systemd: Add Environment=UPLOAD_DIR=/data/images to your service unit file.
• .env file: Add UPLOAD_DIR=/data/images to the .env file loaded by your gateway process.

Troubleshooting

Connection Errors

If you're having trouble connecting:

1. Verify your API key is valid
2. Check the endpoint URL is correct: https://api.llmgateway.io/mcp
3. Ensure your firewall allows outbound HTTPS connections

Tool Not Found

If tools aren't appearing:

1. Restart your MCP client
2. Check the configuration syntax
3. Verify the MCP server is responding: GET https://api.llmgateway.io/mcp

Rate Limiting

The MCP server respects your account's rate limits. If you're hitting limits:

1. Check your usage in the dashboard
2. Consider upgrading your plan
3. Implement request queuing in your application

Benefits

• Unified Access - Discover the live model and provider catalog through one interface
• Cost Tracking - Ask your assistant about usage, spending, and your most-used models, providers, and apps
• Caching - Automatic response caching reduces costs and latency
• Fallback - Automatic provider failover ensures reliability
• Image Generation - Generate images directly from your AI assistant