RelayPlane MCP Server

Reduce AI context usage by 90%+ in multi-step workflows

RelayPlane keeps intermediate results in the workflow engine instead of passing them through your context window—saving tokens and reducing costs.

Table of Contents

• Quick Start
• Installation Options
• Model IDs
• Available Tools
• Budget Protection
• Pre-built Skills
• Configuration
• Troubleshooting

Quick Start

1. Install with API Keys (Recommended)

claude mcp add relayplane \
  -e OPENAI_API_KEY=sk-... \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -- npx @relayplane/mcp-server

2. Restart Claude Code

Important: You must fully restart Claude Code after adding the MCP server. The /mcp command only reconnects—it doesn't reload environment variables.

3. Test the Connection

Ask Claude: "Use relay_models_list to show configured providers"

Models should show configured: true for providers with valid API keys.

Installation Options

Option A: Inline API Keys (Simplest)

claude mcp add relayplane \
  -e OPENAI_API_KEY=sk-proj-... \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e GOOGLE_API_KEY=AIza... \
  -e XAI_API_KEY=xai-... \
  -- npx @relayplane/mcp-server

Option B: Shell Environment Variables

First, add to your shell profile (~/.zshrc or ~/.bashrc):

export OPENAI_API_KEY=sk-proj-...
export ANTHROPIC_API_KEY=sk-ant-...
export GOOGLE_API_KEY=AIza...
export XAI_API_KEY=xai-...

Then source and install:

source ~/.zshrc
claude mcp add relayplane -- npx @relayplane/mcp-server

Option C: Manual Configuration

Edit ~/.claude.json directly:

{
  "projects": {
    "/your/project/path": {
      "mcpServers": {
        "relayplane": {
          "type": "stdio",
          "command": "npx",
          "args": ["@relayplane/mcp-server"],
          "env": {
            "OPENAI_API_KEY": "sk-proj-...",
            "ANTHROPIC_API_KEY": "sk-ant-...",
            "GOOGLE_API_KEY": "AIza...",
            "XAI_API_KEY": "xai-..."
          }
        }
      }
    }
  }
}

Warning: The env field must contain actual API keys, not variable references like ${OPENAI_API_KEY}. Variable substitution is not supported in the MCP config file.

Model IDs

Important: Always check https://relayplane.com/docs/providers for the latest model IDs. The relay_models_list tool may return outdated information.

OpenAI — prefix: openai:

| Model ID | Best For | |------------|-----------------------------| | gpt-5.2 | Latest flagship, 1M context | | gpt-5-mini | Cost-efficient, fast | | gpt-4.1 | Non-reasoning, 1M context | | o3 | Advanced reasoning | | o4-mini | Fast reasoning |

Anthropic — prefix: anthropic:

| Model ID | Best For | |----------------------------|-----------------------------------| | claude-opus-4-5-20251101 | Most intelligent, complex tasks | | claude-sonnet-4-5-20250929 | Best coding, strongest for agents | | claude-haiku-4-5-20251001 | Fast, high-volume tasks | | claude-3-5-haiku-20241022 | Fast, affordable (legacy) |

Google — prefix: google:

| Model ID | Best For | |------------------|--------------------------| | gemini-3-pro | Most powerful multimodal | | gemini-2.5-flash | Fast multimodal | | gemini-2.0-flash | Cost-effective |

xAI — prefix: xai:

| Model ID | Best For | |-------------|-------------------------------| | grok-4 | Latest flagship, 256K context | | grok-3-mini | Fast, quick tasks |

Example Usage

{
  "name": "my-step",
  "model": "openai:gpt-4.1",
  "prompt": "Analyze this data..."
}

Available Tools

| Tool | Purpose | Cost | |-------------------------|--------------------------|-----------| | relay_run | Single prompt execution | Per-token | | relay_workflow_run | Multi-step orchestration | Per-token | | relay_workflow_validate | Validate DAG structure | Free | | relay_skills_list | List pre-built patterns | Free | | relay_models_list | List available models | Free | | relay_runs_list | View recent runs | Free | | relay_run_get | Get run details | Free |

Budget Protection

Default safeguards (customizable via CLI flags):

| Limit | Default | Flag | |-----------------|---------|------------------------| | Daily spending | $5.00 | --max-daily-cost | | Per-call cost | $0.50 | --max-single-call-cost | | Hourly requests | 100 | --max-calls-per-hour |

RelayPlane is BYOK (Bring Your Own Keys)—we don't charge for API usage. Costs reflect only your provider bills.

Pre-built Skills

Use relay_skills_list to see available workflow templates:

| Skill | Context Reduction | Use Case | |-------------------|-------------------|---------------------------------------| | invoice-processor | 97% | Extract, validate, summarize invoices | | content-pipeline | 90% | Generate and refine content | | lead-enrichment | 80% | Enrich contact data |

Configuration

Persistent Config File

Create ~/.relayplane/mcp-config.json:

{
  "codegenOutDir": "./servers/relayplane",
  "maxDailyCostUsd": 10.00,
  "maxSingleCallCostUsd": 1.00,
  "maxCallsPerHour": 200
}

Note: API keys should be passed via environment variables or the Claude Code MCP env field—not stored in this config file.

Troubleshooting

"Provider not configured" Error

Provider "openai" (step "extract") is not configured.
Set OPENAI_API_KEY environment variable.

Causes:

1. API key not passed to MCP server
2. Claude Code not restarted after config change

Solutions:

1. Check your MCP config in ~/.claude.json:

"relayplane": {
  "env": {
    "OPENAI_API_KEY": "sk-..."  // Must be actual key, not ${VAR}
  }
}

2. Fully restart Claude Code (exit with Ctrl+C, relaunch)

3. Verify configuration: Ask Claude: "Use relay_models_list and check which show configured: true"

Model Not Found (404 Error)

Anthropic API error: 404 - model: claude-3-5-sonnet-20241022

Cause: Model ID is outdated or incorrect.

Solution: Check current model IDs at: https://relayplane.com/docs/providers

Common fixes:

• Use claude-3-5-haiku-20241022 instead of claude-3-5-sonnet-20241022
• Use gpt-4.1 instead of gpt-4o for latest OpenAI

Config Changes Not Taking Effect

Cause: /mcp reconnect doesn't reload environment variables.

Solution: Fully restart Claude Code:

1. Exit with Ctrl+C
2. Relaunch claude
3. Run /mcp to verify connection

Workflow Validation Passes But Execution Fails

Cause: relay_workflow_validate only checks DAG structure, not:

• API key validity
• Model availability
• Schema compatibility

Solution: Test with a simple relay_run first:

Use relay_run with model "openai:gpt-4.1" and prompt "Say hello"

Quick Test

After setup, verify everything works:

Use relay_workflow_run to create an invoice processor:
- Step 1 (extract): Use openai:gpt-4.1 to extract vendor, total from invoice
- Step 2 (validate): Use anthropic:claude-3-5-haiku-20241022 to verify math

Input: "Invoice from Acme Corp, Total: $500"

Expected: Both steps complete successfully with structured output.

Support

• Documentation: https://relayplane.com/docs
• Model IDs: https://relayplane.com/docs/providers
• Issues: https://github.com/RelayPlane/mcp-server/issues

License

MIT