# 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