Sphyr MCP Server | Developer Docs

settings

Per-Client Configuration

Copy the config block for your MCP client. The Sphyr MCP Server connects via stdio — no server to run.

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

claude_desktop_config.json

{
  "mcpServers": {
    "sphyr": {
      "command": "npx",
      "args": ["-y", "-p", "@sphyr/sdk", "sphyr-proxy"],
      "env": {
        "SPHYR_API_KEY": "your-api-key",
        "SPHYR_HMAC_SECRET": "your-hmac-secret"
      }
    }
  }
}

Python SDK variant

If you prefer the Python SDK, replace the command and args with:

Python variant

{
  "mcpServers": {
    "sphyr": {
      "command": "python",
      "args": ["-m", "sphyr_sdk.proxy"],
      "env": {
        "SPHYR_API_KEY": "your-api-key",
        "SPHYR_HMAC_SECRET": "your-hmac-secret"
      }
    }
  }
}

code

Generic Template

Use this template for any MCP client that supports stdio servers. Drop it into the client's MCP server configuration block.

Generic MCP server entry (TypeScript)

"sphyr": {
  "command": "npx",
  "args": ["-y", "-p", "@sphyr/sdk", "sphyr-proxy"],
  "env": {
    "SPHYR_API_KEY": "your-api-key",
    "SPHYR_HMAC_SECRET": "your-hmac-secret"
  }
}

lock

Security Model

The Sphyr MCP Server acts as a transparent proxy. Your agent calls tools normally — Sphyr re-signs each request with a fresh HMAC signature and routes it through the security pipeline.

1

HMAC signing

Every tool call is re-signed with your SPHYR_HMAC_SECRET. The original agent request is never forwarded.

2

Session isolation

The proxy manages its own session token (sess_token). Agents never supply or observe session credentials.

3

Trace IDs

Each request gets a unique trace_id for audit log correlation.

loop

Agent Loop

If your agent framework runs its own async event loop, run the Sphyr MCP Server as an independent process — not inside your agent's loop.

info

Python agents using frameworks like LangGraph or AutoGEN typically run their own async event loop. Start the Sphyr MCP Server as a separate ASGI process (e.g., via subprocess or a process manager) rather than nesting it inside your agent framework's loop.