@sigilcore/mcp-proxy

Wraps MCP tool connections in Sigil Intent Attestations. Every tool call is evaluated against your operator's warranty.md policy before it reaches the real MCP server.

MCP action taxonomy and trust

Governed MCP calls submit the namespaced action mcp.<serverId>.<toolName>. The proxy keeps the binding identity in metadata.serverId, the tool name in metadata.toolName, and the complete arguments in metadata.arguments. Sign matches policy against those exact metadata values. It never splits the action string, because server IDs may contain dots, slashes, URLs, or scoped package names.

Use a ## mcp block to allowlist servers and tools, block tool patterns, or place a tool behind a durable approval hold. A trailing * is the only wildcard form. Without a ## mcp block, every MCP action is denied.

The proxy always calls @sigilcore/agent-hooks with failMode: "closed". --unsafe-bypass remains an explicit emergency escape hatch and logs every ungoverned call. A normal client-side npm installation is not a trusted shim: its API key shares the agent environment. Only a controlled deployment with a dedicated credential inaccessible to the governed agent can satisfy a policy's require_shim: true or attested rule.

For PENDING, the proxy polls the authenticated tenant-scoped hold-status endpoint. An operator's APPROVED decision does not authorize the MCP call by itself. The proxy submits the unchanged canonical intent to Sign again, and it forwards the tool call only if that exact-intent retry receives a fresh APPROVED response carrying a fresh intent_attestation. Denial, expiry, timeout, changed intent, consumed approval, a missing attestation, or any unexpected response fails closed.

Quick Start

# Install
npm install -g @sigilcore/mcp-proxy

# Wrap any MCP server
npx @sigilcore/mcp-proxy -- npx @some/mcp-server

# Set your API key
export SIGIL_API_KEY=sk_sigil_YOUR_KEY

MCP Client Config

Change one line in your MCP client config:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["@sigilcore/mcp-proxy", "--", "npx", "@some/pg-mcp"]
    }
  }
}

Configuration

Generate a starter config: npx @sigilcore/mcp-proxy --init

Precedence: CLI flags > environment variables > config file > defaults.

| CLI Flag | Env Var | Config Key | Default | |---|---|---|---| | --key | SIGIL_API_KEY | (env only) | (required) | | --sign-url | SIGIL_SIGN_URL | signUrl | https://sign.sigilcore.com | | --log-level | SIGIL_LOG_LEVEL | logLevel | info | | --server-id | — | serverId | derived from command/URL | | --server-name | — | serverName | same as serverId | | --pending-timeout | SIGIL_PENDING_TIMEOUT | pendingTimeout | 30000 | | --unsafe-bypass | (CLI only) | (CLI only) | false | | --remote | — | — | — | | --port | — | — | auto |

Server Identity

• serverId — Binding identity (security-critical). Used in txCommit preimage and policy evaluation. Auto-derived from the package name (stdio) or full URL (HTTP) if not set.
• serverName — Display label (logs only). Defaults to serverId.

Unsafe Bypass

The proxy is fail-closed by default. When Sign is unreachable, tool calls are blocked.

To allow ungoverned calls during Sign outages, use the --unsafe-bypass CLI flag. This flag is intentionally not available as an env var or config file option — it must be visible in your MCP client config:

npx @sigilcore/mcp-proxy --unsafe-bypass -- npx @some/mcp-server

Every bypassed call emits an ungoverned_tool_call error-level log. Auth failures (401/403) are NEVER bypassed.

HTTP/SSE Transport

Proxy a remote MCP server:

npx @sigilcore/mcp-proxy --remote https://api.example.com/mcp

Upstream Authentication

Remote MCP servers often require auth. Configure upstream headers in your config file using environment variable references:

{
  "upstream": {
    "headers": {
      "Authorization": "Bearer $UPSTREAM_TOKEN",
      "X-Custom-Header": "$CUSTOM_HEADER_VALUE"
    }
  }
}

All header values must reference at least one $IDENTIFIER env var. Raw secrets are rejected at load time.

Convenience shortcut for Authorization header:

export SIGIL_UPSTREAM_AUTH="Bearer sk-abc123..."
npx @sigilcore/mcp-proxy --remote https://api.example.com/mcp

Extractors

Map tool arguments to Sigil policy fields in sigil.config.json:

{
  "extractors": {
    "fetch": { "url": "url" },
    "write_file": { "path": "path" }
  }
}

Error Codes

• -32001 — Sigil policy denial (DENIED, fail-closed, hold timeout)
• -32002 — Sigil authentication failure (invalid API key)

License

MIT