Sphyr

MCP server

Connect any MCP client to Sphyr Agent Guard with a single config entry. No agent code changes required — the proxy handles HMAC signing, session management, and request routing transparently.

stable · API v1
Updated Jun 2, 2026
If you're an agent reading this:
The sphyr_net tool is the primary interface for routing outbound requests through Agent Guard. You'll find the exact call signature in the sphyr_net tool call section below. Make sure to supply cat — the schema has no default.

Per-client configuration

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

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

{
  "mcpServers": {
    "sphyr": {
      "command": "npx",
      "args": ["-y", "-p", "@sphyr/sdk", "sphyr-mcp"],
      "env": {
        "SPHYR_CREDENTIAL": "your-credential"
      }
    }
  }
}

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_CREDENTIAL": "your-credential"
      }
    }
  }
}

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-mcp"],
  "env": {
    "SPHYR_CREDENTIAL": "your-credential"
  }
}

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.

HMAC signing

Every tool call is re-signed using your SPHYR_CREDENTIAL. The original agent request is never forwarded.

Session isolation

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

Trace IDs

Each request gets a unique trace_id for audit log correlation.

Explicit cat required

The MCP proxy requires cat to be supplied explicitly — the sphyr_net schema has no default. Use "api-call" for standard API call monitoring.

sphyr_net tool call

When your agent invokes sphyr_net, the call arguments must include cat — the proxy schema has no default. Example payload:

sphyr_net arguments 
{
  "url": "https://api.example.com/v1/resource",
  "mthd": "GET",
  "cat": "api-call"
}

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.

Python async event loop
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 (via subprocess or a process manager) rather than nesting it inside your agent framework's loop.

Session observability

Each agent session appears in the Sphyr console with a full request log. You'll see total request count, blocked count, and the highest rule severity logged during the session. Expanding a blocked request shows the inline rationale — the specific reason the request was stopped.

Trace session — console view 
# session · a3f8b2c1… · 12 requests · 3 blocked · risk 71

GET  https://api.openai.com/v1/chat/completions  ALLOWED  risk 4
GET  https://api.stripe.com/v1/charges           ALLOWED  risk 11
POST https://api.example.com/upload              BLOCKED  risk 71
  ↳ Entropy threshold exceeded — Shannon entropy 6.42 bits/char on URL parameter value; pattern matches API key format.

# session · c92a1f3d… · 8 requests · 0 blocked · risk 12