MCP Client Guide

How to connect to an OpRelay instance and write facts, decisions, and runs from an agent or script.

Quick Start (MCP-native agents)

If your agent framework supports MCP natively (Claude Code, Cursor, etc.), add this to your MCP config:

{
  "mcpServers": {
    "oprelay": {
      "type": "streamable-http",
      "url": "https://your-host/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_AUTH_TOKEN"
      }
    }
  }
}

Then call tools directly:

upsert_fact({
  project_key: "my-project",
  category: "infra",
  key: "database",
  value_json: '{"engine": "postgres", "version": "16"}',
  auth_token: "YOUR_AUTH_TOKEN"
})

Quick Start (curl / HTTP)

StreamableHTTP requires a session lifecycle. You cannot fire one-shot requests.

Step 1: Initialize

SESSION_ID=$(curl -s -D- -X POST "$ENDPOINT/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {"name": "my-agent", "version": "1.0"}
    }
  }' | grep -i 'mcp-session-id' | tr -d '\r' | awk '{print $2}')

Step 2: Send initialized notification

curl -s -X POST "$ENDPOINT/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{"jsonrpc": "2.0", "method": "notifications/initialized"}'

Step 3: Call tools

curl -s -X POST "$ENDPOINT/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "upsert_fact",
      "arguments": {
        "project_key": "my-project",
        "category": "infra",
        "key": "database",
        "value_json": "{\"engine\": \"postgres\"}",
        "auth_token": "YOUR_AUTH_TOKEN"
      }
    }
  }'

Reuse the same Mcp-Session-Id for all calls in a session.

Required Headers (HTTP)

Header	Value	Notes
Content-Type	application/json	Always
Accept	application/json, text/event-stream	Both required
Authorization	Bearer YOUR_TOKEN	Transport-level auth
Mcp-Session-Id	From init response	Required after initialization

Agent Workflow Pattern

Session start:
  1. get_context(project_key) → load current state
  2. Use facts/decisions to inform your work

During work:
  3. upsert_fact() for operational state worth remembering
  4. upsert_decision() for engineering decisions made

Session end:
  5. record_run() → log what you did