Connecting Desktop Agents

How to connect Claude Code, Cursor, Codex CLI, or any MCP-compatible desktop agent to an OpRelay instance.

Transports

Transport	Best for	Protocol
StreamableHTTP	Remote/hosted instances	HTTP with session lifecycle
stdio	Local development	Direct process spawn

Remote (StreamableHTTP)

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

Where to put the config

Client	Config location
Claude Code	.mcp.json in your project root
Cursor	.cursor/mcp.json in your project root
Codex CLI	codex.json or equivalent MCP config
Other MCP clients	Check your client's MCP configuration docs

A repo-level .mcp.json is recommended — it makes the MCP connection available to any agent working in the repository.

Local (stdio)

{
  "mcpServers": {
    "oprelay": {
      "command": "node",
      "args": ["/path/to/oprelay/server/dist/src/index.js"],
      "env": {
        "MCP_AUTH_TOKEN": "your-token",
        "DATABASE_TYPE": "sqlite"
      }
    }
  }
}

No database setup required — SQLite is the default.

Docker (self-hosted)

{
  "mcpServers": {
    "oprelay": {
      "type": "streamable-http",
      "url": "http://localhost:3100/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_AUTH_TOKEN"
      }
    }
  }
}

Auth

OpRelay uses two layers of authentication:

1. Transport auth — Authorization: Bearer header authenticates the HTTP connection
2. Tool auth — each tool call requires auth_token in its arguments

Both use the same token (MCP_AUTH_TOKEN on the server). When using stdio transport, the header is not needed — only the tool-level auth_token.

If MCP_AUTH_TOKEN is not set on the server, auth is disabled entirely.