bolyra

@bolyra/mcp

MCP ツールの呼び出しを制限し、認可されたエージェントだけが機密性の高いツールを呼び出せるようにします。

クイックスタート（60 秒）

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,
  },
});

これで完了です。以降、すべての tools/call で有効な Bolyra proof bundle が必要になります。

開発モード（完全な例）

開発モードではモック証明を使います。回路アーティファクトや信頼されたセットアップは不要で、すぐに起動できます。実際の ZKP 検証を組み込む前に、サーバーの構築とテストを行うために使用してください。

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());

クライアント側：

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 }, ... });

仕組み

すべての tools/call リクエストには、proof bundle を含める必要があります。これは、共有セッション nonce に紐付けられた 2 つの Groth16 証明（人間の回路からの証明とエージェントの回路からの証明）です。

サーバー側では、次の処理を行います。

1. params._meta.bolyra（stdio）または Authorization: Bolyra <base64> ヘッダー（HTTP）からバンドルを抽出します。
2. ハンドシェイクを検証します（両方の証明、nonce の鮮度、スコアの下限値）。
3. ツールの権限ポリシーをエージェントの有効なビットマスクと照合します。
4. リクエストに BolyraAuthContext を付加し、後続のハンドラーで利用できるようにします。
5. いずれかの手順に失敗した場合は、MCP エラーを返してリクエストを拒否します。

ディスカバリー呼び出し（initialize、tools/list）は認証なしで通過します。

委任チェーン（v=2 バンドル）は、複数のホップを通じてルート認証情報からリーフエージェントへスコープを絞り込みます。ツールポリシーが参照する有効なビットマスクは、常に最も制限されたスコープであるリーフのものです。

API リファレンス

サーバー — stdio

withBolyraAuthStdio(server: McpServer, config: BolyraMcpConfig): void

McpServer インスタンスをラップします。server.connect(transport) の前に呼び出す必要があります。

サーバー — HTTP

bolyraAuthMiddleware(config: BolyraMcpHttpConfig): express.RequestHandler

Express ミドルウェアです。MCP HTTP ハンドラーより前にマウントしてください。認証されていない tools/call リクエストは HTTP 401 で拒否します。

クライアントヘルパー

attachBolyraProof(
  human: HumanIdentity,
  agent: AgentCredential,
  options?: AttachProofOptions,
): Promise<BolyraClientAuth>

ハンドシェイクを実行し、{ headers, meta, bundle } を返します。実際の証明をスキップしてモックバンドルを生成するには、options.devMode = true を設定してください。

attachDelegatedBolyraProof(
  human: HumanIdentity,
  rootCred: AgentCredential,
  hops: DelegationHopSpec[],
  options?: AttachProofOptions,
): Promise<BolyraClientAuth>

attachBolyraProof と同様ですが、委任チェーンをたどり、v=2 バンドルを返します。

検証

verifyBundle(bundle: BolyraProofBundle, config: BolyraMcpConfig): Promise<BolyraAuthContext>

バンドルを直接検証します。カスタムトランスポートやオフライン検証に便利です。

checkToolPolicy(
  toolName: string,
  ctx: BolyraAuthContext,
  policy: ToolPermissionPolicy,
): { allowed: boolean; reason?: string }

BolyraAuthContext がツールに必要なビットマスクを満たしているか確認します。

開発用 ID（SDK から再エクスポート）

createDevIdentities(options?: DevIdentityOptions): Promise<DevIdentities>

固定シードの { human, agent, operatorKey } を返します。決定的に生成され、回路アーティファクトは不要です。初回呼び出し時に警告をログに出力します。本番環境では絶対に使用しないでください。

本番環境の設定

devMode: true を実際の resolveCredential リゾルバーに置き換え、SDK が回路アーティファクトを参照するように設定します。

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',
  },
});

設定インターフェースの全体：

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;
}

HTTP 版では authScheme?: string（デフォルトは "Bolyra"）が追加されます。

トランスポートガイド

トランスポート	バンドルの場所	備考
stdio（Claude Desktop、Cursor、Cline）	params._meta.bolyra	MCP 仕様では stdio 認証用の仕組みが定義されていません。プロトコルレベルで利用できるフィールドは _meta のみです
HTTP / SSE / Streamable-HTTP	Authorization: Bolyra <base64-bundle>	RFC 7235 に準拠したカスタム認証スキームです。OAuth 2.1 のリソースサーバーパターンに沿っています

どちらのトランスポートでも、サーバー側では同じ BolyraAuthContext が生成されます。ツールハンドラーが使用されたトランスポートを把握する必要はありません。

例

開発モードを使った stdio サーバーとクライアントの完全な例については、examples/protected-file-server/ を参照してください。次のコマンドで実行できます。

cd integrations/mcp
npm run example:protected-file-server