{"_id":"@btx-tools/mcp-gateway","_rev":"4-7b8df8e0dac4cf1d357be6cd7a9a2368","name":"@btx-tools/mcp-gateway","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.0":{"name":"@btx-tools/mcp-gateway","version":"0.1.0","keywords":["btx","mcp","model-context-protocol","service-challenges","ai-gateway","agent","agentic-ai","admission-control","rate-limit","proof-of-work","post-quantum"],"author":{"name":"visitor-code","email":"visitor@friction.market"},"license":"MIT","_id":"@btx-tools/mcp-gateway@0.1.0","maintainers":[{"name":"visitor-code","email":"visitor@friction.market"}],"homepage":"https://github.com/btx-tools/btx-mcp-gateway#readme","bugs":{"url":"https://github.com/btx-tools/btx-mcp-gateway/issues"},"dist":{"shasum":"fd3aebe63195d787ad3530934d4d804792c37bcd","tarball":"https://registry.npmjs.org/@btx-tools/mcp-gateway/-/mcp-gateway-0.1.0.tgz","fileCount":20,"integrity":"sha512-oomeFV4cDUwwMFcsQQoSWxCrcxesRIkyJLCzn9jGLR4gStuRlO5yxuZauSZGkernoL6yU3GIpAfgrQGML4SbGw==","signatures":[{"sig":"MEUCIQD4hy4maIgXSrWOIcCdBAesvHFVPRPpsMh1g6W8M0Tv+wIgXVhMrhCXDINi4iF7jswxkq7mTXG0CmYeE4+ThD+I0yc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1338293},"main":"./dist/index.cjs","type":"module","_from":"file:btx-tools-mcp-gateway-0.1.0.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18.17"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}},"./example-tools":{"import":{"types":"./dist/example-tools/index.d.ts","default":"./dist/example-tools/index.js"},"require":{"types":"./dist/example-tools/index.d.cts","default":"./dist/example-tools/index.cjs"}}},"scripts":{"test":"vitest run","build":"tsup","format":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\" \"examples/**/*.ts\"","test:unit":"vitest run tests/unit","type-check":"tsc --noEmit","example:client":"tsx examples/client-demo.ts","example:server":"tsx examples/stdio-server.ts","test:integration":"vitest run tests/integration"},"_npmUser":{"name":"visitor-code","email":"visitor@friction.market"},"_resolved":"/private/var/folders/56/l_0r7hgn6nb30xq5clyrvh_m0000gn/T/4871eacf528553a2dff903d51398fc90/btx-tools-mcp-gateway-0.1.0.tgz","_integrity":"sha512-oomeFV4cDUwwMFcsQQoSWxCrcxesRIkyJLCzn9jGLR4gStuRlO5yxuZauSZGkernoL6yU3GIpAfgrQGML4SbGw==","repository":{"url":"git+https://github.com/btx-tools/btx-mcp-gateway.git","type":"git"},"_npmVersion":"10.9.3","description":"MCP server framework with per-tool-call BTX service-challenge admission. Gate any agent tool behind chain-anchored proof-of-work. Companion to @btx-tools/challenges-sdk.","directories":{},"sideEffects":false,"_nodeVersion":"22.20.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","zod":"^3.23.0","tsup":"^8.3.0","vitest":"^2.1.0","prettier":"^3.3.0","typescript":"^5.6.0","@types/node":"^22.0.0","@btx-tools/challenges-sdk":"^0.1.1","@modelcontextprotocol/sdk":"^1.29.0"},"peerDependencies":{"@btx-tools/challenges-sdk":"^0.1.1","@modelcontextprotocol/sdk":"^1.29.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-gateway_0.1.0_1779492254421_0.32140553679178097","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@btx-tools/mcp-gateway","version":"0.1.1","keywords":["btx","mcp","model-context-protocol","service-challenges","ai-gateway","agent","agentic-ai","admission-control","rate-limit","proof-of-work","post-quantum"],"author":{"name":"visitor-code","email":"visitor@friction.market"},"license":"MIT","_id":"@btx-tools/mcp-gateway@0.1.1","maintainers":[{"name":"visitor-code","email":"visitor@friction.market"}],"homepage":"https://github.com/btx-tools/btx-mcp-gateway#readme","bugs":{"url":"https://github.com/btx-tools/btx-mcp-gateway/issues"},"dist":{"shasum":"4cfe7622ba82c61a838af630557c5d0ff353cf0a","tarball":"https://registry.npmjs.org/@btx-tools/mcp-gateway/-/mcp-gateway-0.1.1.tgz","fileCount":20,"integrity":"sha512-zQg3/GzYgJzkXNZyfncRwe0KHtWu4+HEiOUlWtc49gxSeULdSZHky0ICsrK1kHRlXqUfj9UvwODwrSsDWMfJfw==","signatures":[{"sig":"MEUCIQDl2K/wipXcHzbDVMoXUAuvRhxFJ4GQKSsrdmJxpyi1IQIge7OqLhL/iCzN8AIgOVlGpa5v2PI1y/IthgTIU9Js2eY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":139309},"main":"./dist/index.cjs","type":"module","_from":"file:btx-tools-mcp-gateway-0.1.1.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18.17"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}},"./example-tools":{"import":{"types":"./dist/example-tools/index.d.ts","default":"./dist/example-tools/index.js"},"require":{"types":"./dist/example-tools/index.d.cts","default":"./dist/example-tools/index.cjs"}}},"scripts":{"test":"vitest run","build":"tsup","format":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\" \"examples/**/*.ts\"","test:unit":"vitest run tests/unit","type-check":"tsc --noEmit","example:client":"tsx examples/client-demo.ts","example:server":"tsx examples/stdio-server.ts","test:integration":"vitest run tests/integration"},"_npmUser":{"name":"visitor-code","email":"visitor@friction.market"},"_resolved":"/private/var/folders/56/l_0r7hgn6nb30xq5clyrvh_m0000gn/T/aab7d50ca634f3a1e7a127930ba3ec46/btx-tools-mcp-gateway-0.1.1.tgz","_integrity":"sha512-zQg3/GzYgJzkXNZyfncRwe0KHtWu4+HEiOUlWtc49gxSeULdSZHky0ICsrK1kHRlXqUfj9UvwODwrSsDWMfJfw==","repository":{"url":"git+https://github.com/btx-tools/btx-mcp-gateway.git","type":"git"},"_npmVersion":"10.9.3","description":"MCP server framework with per-tool-call BTX service-challenge admission. Gate any agent tool behind chain-anchored proof-of-work. Companion to @btx-tools/challenges-sdk.","directories":{},"sideEffects":false,"_nodeVersion":"22.20.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","zod":"^3.23.0","tsup":"^8.3.0","vitest":"^2.1.0","prettier":"^3.3.0","typescript":"^5.6.0","@types/node":"^22.0.0","@btx-tools/challenges-sdk":"^0.1.1","@modelcontextprotocol/sdk":"^1.29.0"},"peerDependencies":{"zod":"^3.23.0","@btx-tools/challenges-sdk":"^0.1.1","@modelcontextprotocol/sdk":"^1.29.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-gateway_0.1.1_1779493465408_0.9604499679941825","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@btx-tools/mcp-gateway","version":"0.2.0","keywords":["btx","mcp","model-context-protocol","service-challenges","ai-gateway","agent","agentic-ai","admission-control","rate-limit","proof-of-work","post-quantum"],"author":{"name":"visitor-code","email":"visitor@friction.market"},"license":"MIT","_id":"@btx-tools/mcp-gateway@0.2.0","maintainers":[{"name":"visitor-code","email":"visitor@friction.market"}],"homepage":"https://github.com/btx-tools/btx-mcp-gateway#readme","bugs":{"url":"https://github.com/btx-tools/btx-mcp-gateway/issues"},"dist":{"shasum":"d3f019cbaf03c883037bd5a673a853608d257454","tarball":"https://registry.npmjs.org/@btx-tools/mcp-gateway/-/mcp-gateway-0.2.0.tgz","fileCount":20,"integrity":"sha512-OfqmDiUm2vbC8ub+ZNxqQjEgXtFL26JAxd3FeAZVyQQLQnJJ1CXClW2JKuCH2GB44bDvIPv8BG3Z/LfPXK56Ow==","signatures":[{"sig":"MEUCIQCUYzsbgmnmXM644xzE3yn3XgLf+Q+tEcYgXv/Ord9xZQIgMl/YCKd544XQYk4gSdRgjVEihjmTVgiEkYf3OUzJcs4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":142926},"main":"./dist/index.cjs","type":"module","_from":"file:btx-tools-mcp-gateway-0.2.0.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18.17"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}},"./example-tools":{"import":{"types":"./dist/example-tools/index.d.ts","default":"./dist/example-tools/index.js"},"require":{"types":"./dist/example-tools/index.d.cts","default":"./dist/example-tools/index.cjs"}}},"scripts":{"test":"vitest run","build":"tsup","format":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\" \"examples/**/*.ts\"","test:unit":"vitest run tests/unit","type-check":"tsc --noEmit","example:client":"tsx examples/client-demo.ts","example:server":"tsx examples/stdio-server.ts","test:integration":"vitest run tests/integration"},"_npmUser":{"name":"visitor-code","email":"visitor@friction.market"},"_resolved":"/private/var/folders/56/l_0r7hgn6nb30xq5clyrvh_m0000gn/T/b53920caeeca6be137cf72d139e29b9e/btx-tools-mcp-gateway-0.2.0.tgz","_integrity":"sha512-OfqmDiUm2vbC8ub+ZNxqQjEgXtFL26JAxd3FeAZVyQQLQnJJ1CXClW2JKuCH2GB44bDvIPv8BG3Z/LfPXK56Ow==","repository":{"url":"git+https://github.com/btx-tools/btx-mcp-gateway.git","type":"git"},"_npmVersion":"10.9.3","description":"MCP server framework with per-tool-call BTX service-challenge admission. Gate any agent tool behind chain-anchored proof-of-work. Companion to @btx-tools/challenges-sdk.","directories":{},"sideEffects":false,"_nodeVersion":"22.20.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","zod":"^3.23.0","tsup":"^8.3.0","vitest":"^2.1.0","prettier":"^3.3.0","typescript":"^5.6.0","@types/node":"^22.0.0","@btx-tools/challenges-sdk":"^0.2.0","@modelcontextprotocol/sdk":"^1.29.0"},"peerDependencies":{"zod":"^3.23.0","@btx-tools/challenges-sdk":"^0.2.0","@modelcontextprotocol/sdk":"^1.29.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-gateway_0.2.0_1779494221447_0.9406157143564802","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@btx-tools/mcp-gateway","version":"0.3.0","description":"MCP server framework with per-tool-call BTX service-challenge admission. Gate any agent tool behind chain-anchored proof-of-work. Companion to @btx-tools/challenges-sdk.","author":{"name":"visitor-code","email":"visitor@friction.market"},"license":"MIT","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}},"./example-tools":{"import":{"types":"./dist/example-tools/index.d.ts","default":"./dist/example-tools/index.js"},"require":{"types":"./dist/example-tools/index.d.cts","default":"./dist/example-tools/index.cjs"}}},"scripts":{"build":"tsup","test":"vitest run","test:unit":"vitest run tests/unit","test:integration":"vitest run tests/integration","type-check":"tsc --noEmit","format":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\" \"examples/**/*.ts\"","example:server":"tsx examples/stdio-server.ts","example:client":"tsx examples/client-demo.ts","prepublishOnly":"tsup"},"peerDependencies":{"@btx-tools/challenges-sdk":">=0.2.0 <2.0.0","@modelcontextprotocol/sdk":"^1.29.0","zod":"^3.23.0"},"devDependencies":{"@btx-tools/challenges-sdk":"^1.2.0","@modelcontextprotocol/sdk":"^1.29.0","@types/node":"^22.0.0","prettier":"^3.3.0","tsup":"^8.3.0","tsx":"^4.19.0","typescript":"^5.6.0","vitest":"^2.1.0","zod":"^3.23.0"},"keywords":["btx","mcp","model-context-protocol","service-challenges","ai-gateway","agent","agentic-ai","admission-control","rate-limit","proof-of-work","post-quantum"],"repository":{"type":"git","url":"git+https://github.com/btx-tools/btx-mcp-gateway.git"},"homepage":"https://github.com/btx-tools/btx-mcp-gateway#readme","bugs":{"url":"https://github.com/btx-tools/btx-mcp-gateway/issues"},"publishConfig":{"access":"public"},"engines":{"node":">=18.17"},"sideEffects":false,"_id":"@btx-tools/mcp-gateway@0.3.0","gitHead":"b274d5c75ccd688cd63ab8c2651c599fb06bee7a","_nodeVersion":"22.20.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-cE75oE+fBRzK1XdTGtOl42h04dWy9gbok9d0gT+tZbD7R07zisr5dgh12CaaMAhO2wkU49EJMYNcdEuo+Rtn8w==","shasum":"b59d02ee8bd6cab4e8c67c7deffd80ae64346784","tarball":"https://registry.npmjs.org/@btx-tools/mcp-gateway/-/mcp-gateway-0.3.0.tgz","fileCount":20,"unpackedSize":159325,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDhJJx48DTOx3kGENSHkF07jRjC73kIG+82WhpJRNdr6AIga2KYrS6SGISlb2jpBjTUwOflo9zCCsrP34Zm4FIcikQ="}]},"_npmUser":{"name":"visitor-code","email":"visitor@friction.market"},"directories":{},"maintainers":[{"name":"visitor-code","email":"visitor@friction.market"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-gateway_0.3.0_1779624947782_0.22423806306936855"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-22T23:24:14.273Z","modified":"2026-05-24T12:15:48.104Z","0.1.0":"2026-05-22T23:24:14.662Z","0.1.1":"2026-05-22T23:44:25.565Z","0.2.0":"2026-05-22T23:57:01.584Z","0.3.0":"2026-05-24T12:15:47.940Z"},"bugs":{"url":"https://github.com/btx-tools/btx-mcp-gateway/issues"},"author":{"name":"visitor-code","email":"visitor@friction.market"},"license":"MIT","homepage":"https://github.com/btx-tools/btx-mcp-gateway#readme","keywords":["btx","mcp","model-context-protocol","service-challenges","ai-gateway","agent","agentic-ai","admission-control","rate-limit","proof-of-work","post-quantum"],"repository":{"type":"git","url":"git+https://github.com/btx-tools/btx-mcp-gateway.git"},"description":"MCP server framework with per-tool-call BTX service-challenge admission. Gate any agent tool behind chain-anchored proof-of-work. Companion to @btx-tools/challenges-sdk.","maintainers":[{"name":"visitor-code","email":"visitor@friction.market"}],"readme":"# @btx-tools/mcp-gateway\n\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![npm](https://img.shields.io/npm/v/@btx-tools/mcp-gateway)](https://www.npmjs.com/package/@btx-tools/mcp-gateway)\n\nMCP server framework that gates every tool invocation behind a [BTX](https://btx.dev) service-challenge proof. Companion to [`@btx-tools/challenges-sdk`](https://www.npmjs.com/package/@btx-tools/challenges-sdk).\n\n> **Status**: `0.1.0` — first production release. 15 tests across unit + integration. Built against `@modelcontextprotocol/sdk@^1.29.0`.\n\n## Why\n\nAgentic AI systems need admission control that doesn't depend on identity. API keys assume you know who's calling. Cloudflare Turnstile assumes a browser + human. Agents are code, often anonymous, often shared across users.\n\nBTX service-challenges price each tool call in compute — a chain-anchored proof-of-work that's cheap to verify (~ms) but costs the caller real work to produce. Runaway agents pay per call; legitimate use is invisible.\n\nThis package wraps any MCP tool with the gate. One line, drop in.\n\n```ts\nimport { btxToolWrapper, createBtxMcpServer } from '@btx-tools/mcp-gateway';\nimport { BtxChallengeClient } from '@btx-tools/challenges-sdk';\nimport { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';\nimport { z } from 'zod';\n\nconst client = new BtxChallengeClient({\n  rpcUrl: 'http://127.0.0.1:19334',           // dedicated NON-mining btxd\n  rpcAuth: { user: 'rpcuser', pass: 'rpcpass' },\n});\n\nconst server = createBtxMcpServer({\n  name: 'my-gated-tools',\n  version: '0.1.0',\n  tools: [\n    btxToolWrapper({\n      name: 'expensive_search',\n      description: 'Search a large index. Gated against agent abuse.',\n      inputSchema: { query: z.string() },\n      handler: async ({ query }) => ({\n        content: [{ type: 'text', text: `result for: ${query}` }],\n      }),\n      gate: {\n        client,\n        purpose: 'agent_tool_call',\n        resource: ({ query }) => `tool:expensive_search|q_len:${query.length}`,\n        subject: 'anonymous_agent',\n        issueParams: { target_solve_time_s: 1.0, expires_in_s: 300 },\n      },\n    }),\n  ],\n});\n\nawait server.connect(new StdioServerTransport());\n```\n\n## Install\n\n```bash\nnpm install @btx-tools/mcp-gateway @btx-tools/challenges-sdk @modelcontextprotocol/sdk zod\n```\n\n`@btx-tools/challenges-sdk` and `@modelcontextprotocol/sdk` are peer dependencies — bring your own pinned version.\n\n## How it works\n\nWhen an MCP client calls a wrapped tool, the gate runs first:\n\n```\nagent → tools/call expensive_search { query: \"foo\" }\ngateway ← btxd issue\nagent ← { isError: true, content: [text with challenge envelope] }\n\n[agent solves challenge via @btx-tools/challenges-sdk Solver.solve]\n\nagent → tools/call expensive_search {\n  query: \"foo\",\n  btx_proof: { challenge, nonce64_hex, digest_hex }\n}\ngateway ← btxd redeem\nagent ← { content: [text with actual tool output] }\n```\n\nThe challenge envelope text contains a `marker: \"btx_admission_challenge_required\"` field so MCP clients can distinguish it from ordinary errors. **Do not auto-retry** on receiving an `isError: true` result with this marker — solving the proof-of-work is the caller's responsibility, and a naive auto-retry will loop indefinitely.\n\nReplay protection: each (challenge, nonce, digest) tuple is redeemable exactly once. A second call with the same proof returns `marker: \"btx_admission_failed\"` + `reason: \"already_redeemed\"`.\n\n## API\n\n### `btxToolWrapper(definition)`\n\nWrap a tool definition with BTX admission gating.\n\n| Option | Type | Required | Description |\n|---|---|---|---|\n| `name` | `string` | ✅ | Tool name exposed via `tools/list` |\n| `description` | `string` | | Tool description exposed via `tools/list` |\n| `inputSchema` | `ZodRawShape` | ✅ | Tool's input arguments as a Zod raw shape (e.g. `{ query: z.string() }`). The wrapper automatically injects an optional `btx_proof` field — **don't define one yourself** |\n| `handler` | `(args, extra) => CallToolResult` | ✅ | Tool implementation. Receives parsed args (without `btx_proof`) and `extra` (standard MCP extra + `extra.btx.result` admission context) |\n| `gate.client` | `BtxChallengeClient` | ✅ | The SDK client constructed at boot |\n| `gate.purpose` | `string \\| (args) => string` | ✅ | Logical purpose label — `'agent_tool_call'`, your own, etc. |\n| `gate.resource` | `string \\| (args) => string` | ✅ | Resource identifier — what's being gated. Different for each tool |\n| `gate.subject` | `string \\| (args) => string` | ✅ | Subject identifier — who's being challenged |\n| `gate.issueParams` | `Partial<IssueParams>` | | Forwarded to `client.issue()` — e.g. `target_solve_time_s`, `expires_in_s` |\n\n### `createBtxMcpServer(opts)`\n\nBuild an `McpServer` from a list of wrapped tools. Returns an `McpServer` instance ready to `.connect(transport)`.\n\n| Option | Type | Required |\n|---|---|---|\n| `name` | `string` | ✅ |\n| `version` | `string` | ✅ |\n| `tools` | `WrappedBtxTool[]` | ✅ |\n| `instructions` | `string` | |\n\n## Example tools\n\nThe package ships two illustrative tools under `/example-tools` — `expensive_search` (moderate difficulty) and `secure_calendar_write` (higher difficulty for mutations). They're not exported from the package root; import explicitly:\n\n```ts\nimport { expensiveSearchTool, secureCalendarWriteTool } from '@btx-tools/mcp-gateway/example-tools';\n\nconst server = createBtxMcpServer({\n  name: 'my-gated-tools',\n  version: '0.1.0',\n  tools: [\n    expensiveSearchTool(client),       // target_solve_time_s: 1.0\n    secureCalendarWriteTool(client),   // target_solve_time_s: 4.0\n  ],\n});\n```\n\nSee `examples/stdio-server.ts` for a runnable reference + `examples/client-demo.ts` for an end-to-end driver.\n\n## Performance reality\n\nThis is the same physics constraint that applies to the rest of the SDK. **Read [USE-CASES.md in the SDK repo](https://github.com/btx-tools/btx-challenges-sdk/blob/main/USE-CASES.md) before deploying.**\n\nThe matmul proof-of-work was designed for GPU-fast native mining. Two realistic adopter patterns for MCP:\n\n| Pattern | Solver | Wall-clock at `target_solve_time_s=1.0` |\n|---|---|---|\n| Agent runs alongside a dedicated non-mining btxd | `Solver.solve({ mode: 'rpc', rpcClient })` | ~1 second |\n| Agent in a constrained env (no btxd nearby) | `Solver.solve({ mode: 'pure-js' })` | Hours |\n\n**Realistic deployments:**\n- **High-frequency low-value tools** (search, fetch, summarize) — agents that have access to a non-mining btxd via RPC. Sub-second admission.\n- **Low-frequency high-value tools** (calendar writes, payments, file mutations) — pure-JS-once-per-session is acceptable when the tool is expensive and rare.\n\n**Don't try to use this for casual every-message agent admission with pure-JS solving** — the user experience will be terrible. The whole point is to make tool calls *cost something*. If your tool call should be free, don't gate it.\n\n## Production notes\n\n### Dedicated non-mining btxd\n\n`solvematmulservicechallenge` and `redeemmatmulserviceproof` share the matmul backend with btxd's block-template mining. Point at a btxd with `gen=0` in `btx.conf`. On a mining-loaded node, RPC calls queue 15+ minutes behind block work.\n\n### Transport choice\n\n`@modelcontextprotocol/sdk` ships several transports. `StdioServerTransport` is what agent host clients (Claude Desktop, Cline, mcp-cli) use today. HTTP+SSE is supported in the SDK but not currently shipped as a `@btx-tools/mcp-gateway` example — coming in 0.2.0.\n\n### Per-tool difficulty\n\nDifferent tools can carry different `target_solve_time_s` values. Mutations and privileged ops should require more work than reads:\n\n```ts\nexpensiveSearchTool(client, 1.0)            // moderate cost\nsecureCalendarWriteTool(client, 4.0)         // higher cost\n```\n\nReal adopters should write their own tools, not use the bundled stubs in production.\n\n### Agent client compatibility\n\nMost agent clients today don't natively understand BTX challenges. They'll receive `isError: true` and bubble it up to the agent's reasoning loop, which can then decide to call the tool again with `btx_proof` populated. The `do_not_auto_retry` marker in the response body is a hint to clients that build their own retry logic.\n\nIf you're shipping an MCP client of your own, layer a BTX-aware wrapper that auto-handles the dance (Solver.solve → retry).\n\n## Repo links\n\n- npm: https://www.npmjs.com/package/@btx-tools/mcp-gateway\n- GitHub: https://github.com/btx-tools/btx-mcp-gateway\n- Companion SDK: [`@btx-tools/challenges-sdk`](https://github.com/btx-tools/btx-challenges-sdk)\n- MCP spec: [modelcontextprotocol.io](https://modelcontextprotocol.io/specification/)\n- BTX dev portal: [btx.dev/develop](https://btx.dev/develop/)\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","readmeFilename":"README.md"}