Content
# 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](#quick-start)
- [Installation Options](#installation-options)
- [Model IDs](#model-ids)
- [Available Tools](#available-tools)
- [Budget Protection](#budget-protection)
- [Pre-built Skills](#pre-built-skills)
- [Configuration](#configuration)
- [Troubleshooting](#troubleshooting)
---
## Quick Start
### 1. Install with API Keys (Recommended)
```bash
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)
```bash
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`):
```bash
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:
```bash
source ~/.zshrc
claude mcp add relayplane -- npx @relayplane/mcp-server
```
### Option C: Manual Configuration
Edit `~/.claude.json` directly:
```json
{
"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-5-nano | Ultra-fast, minimal cost |
| o3-mini | Reasoning tasks |
### 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-3-flash | Fast multimodal |
| gemini-2.5-flash | Cost-effective |
### xAI — prefix: `xai:`
| Model ID | Best For |
|------------|-------------------------------|
| grok-beta | Latest flagship, 256K context |
### Example Usage
```json
{
"name": "my-step",
"model": "openai:gpt-5.2",
"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`:
```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`:
```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-sonnet-4-5-20250929` for latest Claude Sonnet
- Use `gpt-5.2` for latest OpenAI flagship model
---
### 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-5.2" 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-5.2 to extract vendor, total from invoice
- Step 2 (validate): Use anthropic:claude-haiku-4-5-20251001 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
