Wrap any MCP server with per-tool permission enforcement, replay protection, and audit receipts without changing server code.
Also known as bolyra/bolyra, @bolyra/shield
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- 158
- Latest version
- 0.1.0
- Last commit
- Nov 11, 2026
- License
- Apache-2.0
What is Shield MCP?
Shield is an MCP server. Wrap any MCP server with per-tool permission enforcement, replay protection, and audit receipts without changing server code.
Summary generated from the project's README
About Shield MCP server
Shield acts as a stdio auth proxy designed to wrap existing MCP servers without requiring any modifications to the original server code. It functions by spawning the target server as a child process and intercepting tools/call requests to enforce security policies. This setup is intended for local MCP servers used in environments like Claude Desktop or Cursor.
Users manage security through a shield.yaml configuration file where they can define tool-specific permissions using a bitmask system. This system includes levels such as READ_DATA, WRITE_DATA, and ACCESS_PII. The proxy provides replay protection via a nonce store and generates audit receipts that are emitted to stderr. To simplify setup, a learn mode can automatically discover available tools and generate a baseline configuration with a default deny policy enabled.
What you can do with it
- 1Generate a security baselineA developer can automatically create a configuration file by scanning a server's tool list in learn mode.
- 2Enforce least privilege accessYou can restrict specific tools to only allow read operations by assigning them a specific bitmask value.
- 3Audit tool executionThe proxy provides a way to track tool usage by sending audit receipts to the error stream.
Written from the project's README. Every use case is checked against a quote from it.
How to install Shield MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Shield MCP in Claude Code
$ claude mcp add shield -- npx -y @bolyra/shieldInstall Shield MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"shield": {
"command": "npx",
"args": [
"-y",
"@bolyra/shield"
]
}
}
}Install Shield MCP in VS Code
.vscode/mcp.json
{
"servers": {
"shield": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@bolyra/shield"
]
}
}
}Install Shield MCP in VS Code CLI
$ code --add-mcp '{"name":"shield","type":"stdio","command":"npx","args":["-y","@bolyra/shield"]}'Install Shield MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"shield": {
"command": "npx",
"args": [
"-y",
"@bolyra/shield"
]
}
}
}Install Shield MCP in Codex
$ codex mcp add shield -- npx -y @bolyra/shieldInstall Shield MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.shield] command = "npx" args = ["-y", "@bolyra/shield"]
Install Shield MCP in Gemini CLI
$ gemini mcp add -s user shield npx -- -y @bolyra/shieldInstall Shield MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"shield": {
"command": "npx",
"args": [
"-y",
"@bolyra/shield"
]
}
}
}Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablebolyra/bolyra is public and reachablegithub.com/bolyra/bolyra ↗Pass
- Package names this repository as its source@bolyra/shield names bolyra/bolyra as sourcenpmjs.com/package/@bolyra/shield ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-11github.com/bolyra/bolyra ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @bolyra/shieldPass
- No critical advisory in the package or its dependencies111 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub@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
_generatedprovenance 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 authtools/call— proof extracted fromparams._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
Shield MCP questions
How do I add Shield MCP to Claude Code?
Run claude mcp add shield -- npx -y @bolyra/shield in your terminal. Add --scope user to make it available in every project.
How do I add Shield MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Do I need to change my existing MCP server code to use Shield?
No, Shield acts as a proxy that wraps your existing server with no code changes required.
What happens if a tool is not explicitly listed in the configuration?
By default, tools without a policy entry are allowed. However, you can set defaultDeny to true to reject any tool not listed in the configuration.
Where are the audit receipts sent?
Audit receipts are emitted to stderr, as stdout is reserved for the MCP transport.