shield

@bolyra/shield

Stdio MCP auth proxy. Wrap any MCP server with per-tool permission enforcement, replay protection, and audit receipts. No code changes to the server.

Quick Start

npx @bolyra/shield --server "npx @modelcontextprotocol/server-filesystem /tmp" --dev

Shield spawns the target server as a child process, intercepts tools/call requests, verifies agent credentials, and enforces tool policies before forwarding.

Config

Create shield.yaml:

devMode: true
defaultDeny: true

nonce:
  store: memory
  maxProofAge: 300

receipts:
  enabled: true
  output: stderr

tools:
  read_file:
    requireBitmask: 1    # READ_DATA
  write_file:
    requireBitmask: 2    # WRITE_DATA
  delete_file:
    requireBitmask: 2    # WRITE_DATA

Then:

npx @bolyra/shield --server "node my-server.js" --config shield.yaml

Default Deny

By default, tools without a policy entry are allowed through (only authentication is checked). Set defaultDeny: true to reject any tools/call for tool names not listed in the tools: map.

Learn Mode

Don't write the config by hand — generate a safe starting point from the server's own tool list:

npx @bolyra/shield --learn --server "node my-server.js"

Learn mode spawns the server, performs the MCP handshake (initialize → notifications/initialized → tools/list, following pagination), then writes shield.yaml (or the --config path) with:

• defaultDeny: true — anything the server adds later is rejected until you allow it
• every discovered tool at requireBitmask: 1 (READ_DATA) — the least-privilege floor
• a _generated provenance block (source command + timestamp)

It never overwrites an existing config file, caps pagination at 50 pages, and times out after 30 seconds. The output is a starting point: review each tool and raise its requireBitmask (e.g. write_file → 2) before production use.

How It Works

Agent ←stdin/stdout→ Shield ←stdin/stdout→ MCP Server
                       │
                 verifyBundle()
                 checkToolPolicy()
                 nonceStore.markIfFresh()
                 emitReceipt()

• initialize, tools/list, ping — forwarded without auth
• tools/call — proof extracted from params._meta.bolyra, verified, policy checked, then forwarded or rejected
• Receipts emitted to stderr (stdout is the MCP transport)

Permission Bitmask

Bit	Permission
0	READ_DATA
1	WRITE_DATA
2	FINANCIAL_SMALL
3	FINANCIAL_MEDIUM
4	FINANCIAL_UNLIMITED
5	SIGN_ON_BEHALF
6	SUB_DELEGATE
7	ACCESS_PII

Shield vs Gateway

	Shield	Gateway
Transport	stdio	HTTP
Use case	Local MCP servers (Claude Desktop, Cursor)	Remote/networked MCP servers
How it wraps	Spawns child process	Reverse proxy
Proof source	params._meta.bolyra	Authorization: Bolyra <base64> header
Receipts	stderr	stdout/file/webhook

Both use the same verifyBundle() and checkToolPolicy() from @bolyra/mcp.

Library Usage

import { createShield, loadShieldConfig } from '@bolyra/shield';

const config = loadShieldConfig('./shield.yaml');
const { child, stop } = createShield(config);

Links

• Gateway (HTTP) — for HTTP MCP servers
• MCP Middleware — for embedding auth in your server code
• Bolyra docs