MCP Integration - LLM Gateway

What is MCP?

The Model Context Protocol (MCP) is an open standard that allows AI models to securely interact with external tools, data sources, and services. LLM Gateway implements MCP to enable:

File system access: Read and write local files
Database queries: Connect to SQL/NoSQL databases
API integrations: Call external REST/GraphQL APIs
Custom tools: Execute any function or service
Real-time data: Access live information sources

MCP is supported by Claude Code, Cursor, Windsurf, and other AI development tools.

Architecture

LLM Gateway provides an MCP server that:

Exposes tools for LLM operations (chat, list-models, generate-image)
Authenticates using your API keys
Routes requests through the gateway
Returns responses in MCP format

AI Tool (Claude Code)
       ↓
   MCP Client
       ↓
LLM Gateway MCP Server (HTTP/SSE)
       ↓
Provider APIs (OpenAI, Anthropic, etc.)

Authentication

LLM Gateway’s MCP server supports OAuth 2.0 authentication for seamless integration with AI tools.

OAuth Flow

The server implements:

Authorization endpoint: /oauth/authorize
Token endpoint: /oauth/token
Registration endpoint: /oauth/register
Metadata: /.well-known/oauth-authorization-server

Supported Grant Types

Authorization Code
Client Credentials

Standard OAuth flow with PKCE (Proof Key for Code Exchange):

Client redirects user to /oauth/authorize
User authorizes with their API key
Server returns authorization code
Client exchanges code for access token
Client uses token for MCP requests

Used by: Claude Code, Cursor, Windsurf

Direct API key authentication:

Client sends API key to /oauth/token
Server validates and returns token
Client uses token for MCP requests

Used by: Server-to-server integrations

Registering a Client

Before using OAuth, register your client:

curl -X POST https://api.llmgateway.io/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your-llm-gateway-api-key",
    "client_name": "My AI Tool",
    "redirect_uris": [
      "https://localhost:8080/callback",
      "http://127.0.0.1:8080/callback"
    ]
  }'

Response:

{
  "client_id": "your-llm-gateway-api-key",
  "client_secret": "your-llm-gateway-api-key",
  "client_name": "My AI Tool",
  "redirect_uris": [
    "https://localhost:8080/callback",
    "http://127.0.0.1:8080/callback"
  ],
  "grant_types": ["authorization_code", "client_credentials"],
  "token_endpoint_auth_method": "client_secret_basic"
}

For MCP, the client_id and client_secret are both your LLM Gateway API key.

MCP Endpoints

Server Endpoint

https://api.llmgateway.io/mcp

Methods:

GET: Establish SSE connection or get server info
POST: Send JSON-RPC requests
DELETE: Terminate session

Server Information

Get server metadata:

curl https://api.llmgateway.io/mcp \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "name": "llmgateway",
  "version": "1.0.0",
  "description": "LLM Gateway MCP Server - Access multiple LLM providers through a unified API",
  "protocolVersion": "2024-11-05",
  "capabilities": {
    "tools": {}
  }
}

SSE Connection (Streamable Transport)

Establish a persistent connection for real-time updates:

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

The server returns:

Session ID in mcp-session-id header
Endpoint URL via SSE event
Messages as they’re processed

Available Tools

The MCP server exposes these tools:

1. chat

Generate text responses using any LLM. Use for: Text generation, conversations, analysis, coding, etc.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "chat",
    "arguments": {
      "model": "gpt-4o",
      "messages": [
        {"role": "user", "content": "Explain quantum computing"}
      ],
      "temperature": 0.7,
      "max_tokens": 500
    }
  }
}

Parameters:

Parameter	Type	Required	Description
`model`	string	Yes	Model ID (e.g., “gpt-4o”)
`messages`	array	Yes	Conversation history
`temperature`	number	No	Randomness (0.0-2.0)
`max_tokens`	number	No	Max response length

2. list-models

List all available LLM models with capabilities and pricing.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "list-models",
    "arguments": {
      "family": "openai",
      "limit": 10
    }
  }
}

Parameters:

Parameter	Type	Description
`family`	string	Filter by provider (“openai”, “anthropic”, etc.)
`limit`	number	Max models to return (default: 20)
`include_deactivated`	boolean	Include inactive models
`exclude_deprecated`	boolean	Exclude deprecated models

3. generate-image

Create images from text descriptions. Use for: Image generation, artwork, diagrams, etc.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "generate-image",
    "arguments": {
      "prompt": "A serene mountain landscape at sunset",
      "model": "qwen-image-plus",
      "size": "1024x1024",
      "n": 1
    }
  }
}

Parameters:

Parameter	Type	Description
`prompt`	string	Image description
`model`	string	Image model (default: “qwen-image-plus”)
`size`	string	Image dimensions (e.g., “1024x1024”)
`n`	number	Number of images (1-4)

Response format: Images are returned as base64-encoded data URLs or as MCP image content blocks.

4. generate-nano-banana

Generate images using Gemini 3 Pro Image Preview with file saving.

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "generate-nano-banana",
    "arguments": {
      "prompt": "Cyberpunk cityscape at night",
      "aspect_ratio": "16:9",
      "filename": "cityscape.png"
    }
  }
}

Parameters:

Parameter	Type	Description
`prompt`	string	Image description
`aspect_ratio`	string	”1:1”, “16:9”, “4:3”, or “5:4”
`filename`	string	Optional filename (saved to UPLOAD_DIR)

Set UPLOAD_DIR environment variable to enable file saving.

5. list-image-models

List all available image generation models.

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "list-image-models",
    "arguments": {}
  }
}

Returns models with imageGenerations: true capability.

Client Setup

Claude Code

Configure Claude Code to use LLM Gateway’s MCP server:

Install Claude Code

Follow the official installation guide at anthropic.ai/claude-code.

Add MCP Server

Edit your Claude Code config file:macOS/Linux: ~/.claude/mcp-servers.jsonWindows: %APPDATA%\Claude\mcp-servers.json

{
  "mcpServers": {
    "llmgateway": {
      "url": "https://api.llmgateway.io/mcp",
      "type": "sse",
      "auth": {
        "type": "oauth2",
        "authorization_endpoint": "https://api.llmgateway.io/oauth/authorize",
        "token_endpoint": "https://api.llmgateway.io/oauth/token",
        "client_id": "your-api-key"
      }
    }
  }
}

Restart Claude Code

Restart the application to load the new MCP server.

Authorize

Claude Code will prompt for authorization. Follow the OAuth flow to grant access.

See the Claude Code setup guide for detailed instructions.

Cursor

Add LLM Gateway as an MCP server in Cursor:

Open Settings

Press Cmd/Ctrl + , to open settings.

Navigate to MCP

Go to Extensions → MCP Servers.

Add Server

Click Add Server and enter:

Name: LLM Gateway
URL: https://api.llmgateway.io/mcp
Auth: OAuth 2.0
API Key: Your LLM Gateway API key

Connect

Click Connect and authorize the integration.

See the Cursor setup guide for more details.

Custom Client

Build your own MCP client:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";

const client = new Client({
  name: "my-mcp-client",
  version: "1.0.0",
});

const transport = new SSEClientTransport(
  new URL("https://api.llmgateway.io/mcp"),
  {
    headers: {
      Authorization: `Bearer YOUR_API_KEY`,
    },
  }
);

await client.connect(transport);

// List available tools
const tools = await client.listTools();
console.log("Available tools:", tools);

// Call the chat tool
const result = await client.callTool({
  name: "chat",
  arguments: {
    model: "gpt-4o",
    messages: [{role: "user", content: "Hello!"}],
  },
});

console.log("Response:", result);

Session Management

MCP connections use sessions to maintain state:

Creating a Session

Send GET request with Accept: text/event-stream
Receive mcp-session-id header
Use session ID for subsequent requests

Using Sessions

Include session ID in POST requests:

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

Terminating Sessions

curl -X DELETE https://api.llmgateway.io/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "mcp-session-id: YOUR_SESSION_ID"

Sessions automatically clean up after disconnection.

Security Considerations

Important security practices:

Never expose API keys in client-side code
Use HTTPS for all MCP connections
Implement rate limiting on your end
Rotate API keys regularly
Monitor usage for anomalies

Session Ownership

Sessions are tied to API keys:

Each session belongs to one API key
Attempts to use a session with a different key are rejected
This prevents session hijacking

Redirect URI Validation

For OAuth flows:

Redirect URIs must be registered during client registration
Loopback addresses (localhost, 127.0.0.1) are allowed per RFC 8252
HTTPS required for non-loopback URIs
Prevents authorization code interception

Error Handling

MCP uses JSON-RPC error codes:

Code	Message	Description
-32700	Parse error	Invalid JSON
-32600	Invalid Request	Malformed request
-32601	Method not found	Unknown method
-32602	Invalid params	Invalid parameters
-32603	Internal error	Server error
-32001	Unauthorized	Authentication failed

Example error response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "Authentication required. Provide API key via Authorization header or x-api-key."
  }
}

Best Practices

Connection Management

Reuse SSE connections when possible
Implement reconnection logic with exponential backoff
Close sessions when done to free resources
Monitor connection health with ping requests

Error Handling

Handle all JSON-RPC error codes
Retry transient errors (500, 503)
Don’t retry auth errors (401, 403)
Log errors for debugging
Provide user-friendly error messages

Performance

Batch requests when possible
Cache model lists locally
Stream responses for better UX
Use appropriate timeouts
Monitor latency and throughput

Security

Store API keys securely (env vars, secrets manager)
Validate all inputs before sending
Implement rate limiting
Monitor for unusual activity
Rotate keys periodically

Troubleshooting

Connection Refused

Possible causes:

Invalid API key
Network issues
Firewall blocking requests

Solutions:

Verify API key is correct
Check network connectivity
Ensure firewall allows HTTPS

Session Ownership Error

Error: “Session belongs to a different API key”Cause: Trying to use a session ID with a different API keySolution: Create a new session or use the correct API key

OAuth Redirect Mismatch

Error: “Invalid redirect_uri”Cause: Redirect URI not registered for clientSolution: Register the redirect URI via /oauth/register

Tool Not Found

Error: “Method not found: tools/call”Cause: Incorrect JSON-RPC request formatSolution: Ensure proper request structure (see examples above)

Next Steps

AI Tools Setup

Configure Claude Code, Cursor, and Windsurf.

API Reference

Explore the complete API documentation.

Playground

Test MCP tools in the interactive playground.

Projects

Manage API keys and project settings.

Get Started

Core Features

Guides

Integrations

​What is MCP?

​Architecture

​Authentication

​OAuth Flow

​Supported Grant Types

​Registering a Client

​MCP Endpoints

​Server Endpoint

​Server Information

​SSE Connection (Streamable Transport)

​Available Tools

​1. chat

​2. list-models

​3. generate-image

​4. generate-nano-banana

​5. list-image-models

​Client Setup

​Claude Code

​Cursor

​Custom Client

​Session Management

​Creating a Session

​Using Sessions

​Terminating Sessions

​Security Considerations

​Session Ownership

​Redirect URI Validation

​Error Handling

​Best Practices

​Troubleshooting

​Next Steps

AI Tools Setup

API Reference

Playground

Projects

Build docs developers (and LLMs) love

What is MCP?

Architecture

Authentication

OAuth Flow

Supported Grant Types

Registering a Client

MCP Endpoints

Server Endpoint

Server Information

SSE Connection (Streamable Transport)

Available Tools

1. chat

2. list-models

3. generate-image

4. generate-nano-banana

5. list-image-models

Client Setup

Claude Code

Cursor

Custom Client

Session Management

Creating a Session

Using Sessions

Terminating Sessions

Security Considerations

Session Ownership

Redirect URI Validation

Error Handling

Best Practices

Troubleshooting

Next Steps