Gate MCP tool calls by requiring authorized agents to provide cryptographic proof bundles before accessing sensitive tools.
Also known as bolyra/bolyra, @bolyra/mcp
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- 608
- Latest version
- 0.6.4
- Last commit
- Nov 11, 2026
- License
- Apache-2.0
What is Bolyra MCP?
Bolyra is an MCP server. Gate MCP tool calls by requiring authorized agents to provide cryptographic proof bundles before accessing sensitive tools.
Summary generated from the project's README
About Bolyra MCP server
Securing sensitive tool access by requiring cryptographic proof bundles is what this server enables for developers building MCP integrations. It acts as a gatekeeper that ensures only authorized agents can execute specific commands, such as reading or writing files, by verifying Groth16 proofs from both a human and an agent. This mechanism prevents unauthorized tool calls while allowing discovery calls like list tools to remain unauthenticated.
Developers can implement this using the withBolyraAuthStdio function for local stdio connections or the bolyraAuthMiddleware for HTTP-based servers. The system uses a tool policy defined by BigInt bitmasks to distinguish between different permission levels, such as 1n for reading data and 2n for writing data. For testing, a devMode setting provides mock proofs that allow for instant startup without requiring real zero-knowledge proof circuit artifacts. The server extracts authentication bundles from the _meta field in stdio or via the Authorization header in HTTP environments.
What you can do with it
- 1Test authentication logic locallyUse mock identities and proofs to build and verify your server logic before implementing real zero-knowledge verification.
- 2Implement delegated permission chainsManage complex authorization scenarios where permissions are narrowed across multiple hops from a root credential to a leaf agent.
- 3Secure HTTP-based MCP endpointsProtect remote MCP services by requiring a Bolyra authorization header in incoming requests.
Written from the project's README. Every use case is checked against a quote from it.
How to install Bolyra MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Bolyra MCP in Claude Code
$ claude mcp add mcp -- npx -y @bolyra/mcpInstall Bolyra MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@bolyra/mcp"
]
}
}
}Install Bolyra MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@bolyra/mcp"
]
}
}
}Install Bolyra MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp","type":"stdio","command":"npx","args":["-y","@bolyra/mcp"]}'Install Bolyra MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@bolyra/mcp"
]
}
}
}Install Bolyra MCP in Codex
$ codex mcp add mcp -- npx -y @bolyra/mcpInstall Bolyra MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp] command = "npx" args = ["-y", "@bolyra/mcp"]
Install Bolyra MCP in Gemini CLI
$ gemini mcp add -s user mcp npx -- -y @bolyra/mcpInstall Bolyra MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@bolyra/mcp"
]
}
}
}Automated checks
Ran Nov 13, 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/mcp names bolyra/bolyra as sourcenpmjs.com/package/@bolyra/mcp ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @bolyra/mcpnpmjs.com/package/@bolyra/mcp/v/0.6.4#provenance ↗Pass
- 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/mcpPass
- No critical advisory in the package or its dependencies109 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/mcp
Gate MCP tool calls so only authorized agents can call sensitive tools.
Quick Start (60 seconds)
npm install @bolyra/mcp @bolyra/sdk @modelcontextprotocol/sdk
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { withBolyraAuthStdio } from '@bolyra/mcp';
const server = new McpServer({ name: 'my-server', version: '1.0.0' });
server.tool('read_file', { path: { type: 'string' } }, async (args) => ({
content: [{ type: 'text', text: `Reading ${args.path}` }],
}));
withBolyraAuthStdio(server.server, {
devMode: true,
toolPolicy: {
// 1n = READ_DATA, 2n = WRITE_DATA (BigInt — add 'n' suffix)
read_file: 1n,
},
});
That's it. Every tools/call now requires a valid Bolyra proof bundle.
Dev mode (full example)
Dev mode uses mock proofs — no circuit artifacts, no trusted setup, instant startup. Use it to build and test your server before wiring real ZKP verification.
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { withBolyraAuthStdio } from '@bolyra/mcp';
// Server
const server = new McpServer({ name: 'my-server', version: '1.0.0' });
server.tool('read_file', { path: { type: 'string' } }, async (args) => ({
content: [{ type: 'text', text: 'file contents...' }],
}));
withBolyraAuthStdio(server.server, {
devMode: true,
toolPolicy: {
// 1n = READ_DATA, 2n = WRITE_DATA (BigInt — add 'n' suffix)
read_file: 1n,
write_file: 2n,
},
});
await server.connect(new StdioServerTransport());
Client side:
import { createDevIdentities, attachBolyraProof } from '@bolyra/sdk';
const { human, agent } = await createDevIdentities();
const auth = await attachBolyraProof(human, agent, { devMode: true });
// stdio
await client.callTool({ name: 'read_file', arguments: { path: '/tmp/x' }, _meta: auth.meta });
// HTTP
await fetch('/mcp', { headers: { ...auth.headers }, ... });
How it works
Every tools/call request must carry a proof bundle: a pair of Groth16 proofs (one from the human's circuit, one from the agent's) bound to a shared session nonce.
The server side:
- Extracts the bundle from
params._meta.bolyra(stdio) or theAuthorization: Bolyra <base64>header (HTTP). - Verifies the handshake — both proofs, nonce freshness, score floor.
- Checks the tool's permission policy against the agent's effective bitmask.
- Attaches a
BolyraAuthContextto the request for downstream handlers. - Rejects with an MCP error if any step fails.
Discovery calls (initialize, tools/list) pass through unauthenticated.
Delegation chains (v=2 bundles) narrow scope from root credential to leaf agent across multiple hops. The effective bitmask seen by tool policies is always the leaf's — the most-restricted scope.
API reference
Server — stdio
withBolyraAuthStdio(server: McpServer, config: BolyraMcpConfig): void
Wraps an McpServer instance. Must be called before server.connect(transport).
Server — HTTP
bolyraAuthMiddleware(config: BolyraMcpHttpConfig): express.RequestHandler
Express middleware. Mount before your MCP HTTP handler. Rejects unauthenticated tools/call requests with HTTP 401.
Client helpers
attachBolyraProof(
human: HumanIdentity,
agent: AgentCredential,
options?: AttachProofOptions,
): Promise<BolyraClientAuth>
Runs a handshake and returns { headers, meta, bundle }. Pass options.devMode = true to skip real proving and emit a mock bundle.
attachDelegatedBolyraProof(
human: HumanIdentity,
rootCred: AgentCredential,
hops: DelegationHopSpec[],
options?: AttachProofOptions,
): Promise<BolyraClientAuth>
Like attachBolyraProof but walks a delegation chain and returns a v=2 bundle.
Verification
verifyBundle(bundle: BolyraProofBundle, config: BolyraMcpConfig): Promise<BolyraAuthContext>
Verify a bundle directly — useful for custom transports or offline verification.
checkToolPolicy(
toolName: string,
ctx: BolyraAuthContext,
policy: ToolPermissionPolicy,
): { allowed: boolean; reason?: string }
Check a BolyraAuthContext against a tool's required bitmask.
Dev identities (re-exported from SDK)
createDevIdentities(options?: DevIdentityOptions): Promise<DevIdentities>
Returns fixed-seed { human, agent, operatorKey } — deterministic, no circuit artifacts required. Logs a warning on first call. Never use in production.
Production configuration
Swap devMode: true for a real resolveCredential resolver and point the SDK at your circuit artifacts:
withBolyraAuthStdio(server, {
resolveCredential: async (commitment) => myRegistry.get(commitment),
toolPolicy: {
// 1n = READ_DATA, 2n = WRITE_DATA (BigInt — add 'n' suffix)
read_file: 1n,
write_file: 2n,
},
sdkConfig: {
circuitDir: '/path/to/circuits/build',
rpcUrl: 'https://sepolia.base.org',
registryAddress: '0x2781dF8b6381462d881C833Fb703d68c661c9577',
},
});
Full config interface:
interface BolyraMcpConfig {
network?: string; // DID network label (default: 'base-sepolia')
minScore?: number; // Minimum score floor 0–100 (default: 70)
maxProofAge?: number; // Nonce freshness window in seconds (default: 300)
toolPolicy?: ToolPermissionPolicy;
devMode?: boolean; // Mock verification — dev/test only
resolveCredential?: (commitment: string) => Promise<AgentCredential | null>;
sdkConfig?: BolyraConfig;
}
The HTTP variant adds authScheme?: string (default "Bolyra").
Transport guide
| Transport | Bundle location | Notes |
|---|---|---|
| stdio (Claude Desktop, Cursor, Cline) | params._meta.bolyra |
MCP spec defines no stdio auth surface; _meta is the only protocol-level field |
| HTTP / SSE / Streamable-HTTP | Authorization: Bolyra <base64-bundle> |
Custom auth scheme per RFC 7235; aligns with OAuth 2.1 resource-server pattern |
Both produce the same BolyraAuthContext on the server side. Tool handlers don't need to know which transport was used.
Example
See examples/protected-file-server/ for a complete stdio server + client pair using dev mode. Run it with:
cd integrations/mcp
npm run example:protected-file-server
Bolyra MCP questions
How do I add Bolyra MCP to Claude Code?
Run claude mcp add mcp -- npx -y @bolyra/mcp in your terminal. Add --scope user to make it available in every project.
How do I add Bolyra MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How does the server handle authentication for different transports?
For stdio transport, the proof bundle is extracted from params._meta.bolyra, while for HTTP/SSE, it uses the Authorization: Bolyra <base64> header.
Can I test the server without setting up real zero-knowledge proofs?
Yes, you can use dev mode which uses mock proofs for instant startup and testing before wiring real ZKP verification.
Are discovery calls like list tools protected by authentication?
No, discovery calls such as initialize and tools/list are allowed to pass through unauthenticated.