Shield

io.github.bolyraPublished by GitHub account bolyrav0.1.0Updated Oct 24, 2026

Stdio MCP auth proxy: wrap any MCP server with per-tool permission enforcement.

VerifiedSTDIODesktop onlyDeveloper ToolsSecurity & Monitoring

Overview

AI-generated overview

A local stdio proxy that wraps any MCP server to enforce per-tool permissions, replay protection and audit receipts on tool calls.

What you can do
Wrap a target MCP server as a child process and intercept its tool calls before forwarding them, without changing the server's code. Verify agent credentials and check each tool call against a permission policy, rejecting calls that fail. Enforce a default-deny mode so tools without a policy entry are refused. Generate a starting shield.yaml from the server's own tool list in learn mode, with default deny and least-privilege permissions. Emit audit receipts to stderr and use a nonce store to reject replayed proofs. Also usable as a library for embedding the proxy in code.
When to use it
Use it when you run local stdio MCP servers, such as in Claude Desktop or Cursor, and want to restrict which tools an agent may call, require credentials per tool, or keep an audit trail of tool calls without modifying the server.
Requirements
Runs locally over stdio via the npm package, typically started with npx, so Node.js is needed. A target server command to wrap and a shield.yaml config file, which learn mode can generate. No environment variables or headers are declared.
Before you install
It sits between the agent and the wrapped server and decides which tool calls are allowed, so a misconfigured policy can block needed tools or let through tools you meant to restrict; tools without a policy entry are allowed by default unless defaultDeny is set. Learn mode assigns only the READ_DATA permission, so review and raise permissions before production use. Permission bits include financial and sign-on-behalf categories, so check policies carefully for tools that spend money or act for a

Installation

In SourceWeft

  1. Open Shield in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

@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

bash
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:

yaml
devMode: truedefaultDeny: 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:

bash
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:

bash
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

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

Shield vs Gateway

ShieldGateway
TransportstdioHTTP
Use caseLocal MCP servers (Claude Desktop, Cursor)Remote/networked MCP servers
How it wrapsSpawns child processReverse proxy
Proof sourceparams._meta.bolyraAuthorization: Bolyra <base64> header
Receiptsstderrstdout/file/webhook

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

Library Usage

typescript
import { createShield, loadShieldConfig } from '@bolyra/shield';
const config = loadShieldConfig('./shield.yaml');const { child, stop } = createShield(config);

Links

Source: integrations/shield/README.md at commit 5e9de85

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts