{"_id":"@apiosk/mcp","_rev":"4-c96b8ee73f42b253519a1be16a631088","name":"@apiosk/mcp","dist-tags":{"latest":"1.7.0"},"versions":{"1.3.0":{"name":"@apiosk/mcp","version":"1.3.0","keywords":["mcp","apiosk","api","model-context-protocol","x402","agent-tools","payments"],"author":{"name":"Apiosk"},"license":"MIT","_id":"@apiosk/mcp@1.3.0","maintainers":[{"name":"olivierbrinkman","email":"ollybrinkman@gmail.com"}],"homepage":"https://apiosk.com","bugs":{"url":"https://github.com/apiosk/mcp/issues"},"bin":{"apiosk":"index.mjs","apiosk-mcp":"index.mjs","apiosk-mcp-server":"index.mjs"},"dist":{"shasum":"08b50be9d86aebeb492f5f1702927fde09dd8f1c","tarball":"https://registry.npmjs.org/@apiosk/mcp/-/mcp-1.3.0.tgz","fileCount":18,"integrity":"sha512-i6u7UWFpqu/u2xaPKSVMwk//Vvxa0MVY1b9gyp0UmRdkAeuLGUnXr/MdQnTeINOiFeLYzL6VsFiRG5bG8PKcpg==","signatures":[{"sig":"MEUCIQChXkRnzQEK9DGGjtntITGm9xGkPx2n6hfLhHHi0IKFhQIgHDWgnI7kMybCNRMf48kO4nn57HKJZXLDp3afgET/9lo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":235182},"main":"index.mjs","type":"module","engines":{"node":">=20.0.0"},"exports":{".":"./src/create-server.mjs","./runtime":"./src/runtime.mjs","./package.json":"./package.json"},"gitHead":"f1f6fdc2d1dee7b0b7069514c51a0cd56fb51c92","mcpName":"io.github.obcraft/apiosk-mcp","scripts":{"dev":"node server.mjs","test":"node --test","start":"node server.mjs","test:live":"bash scripts/test-live-url.sh","pack:check":"npm pack --dry-run","smoke:new-env":"bash scripts/smoke-new-env.sh","test:macbook-air":"bash scripts/test-macbook-air.sh"},"_npmUser":{"name":"olivierbrinkman","email":"ollybrinkman@gmail.com"},"repository":{"url":"git+https://github.com/apiosk/mcp.git","type":"git"},"_npmVersion":"11.4.2","description":"Official MCP server for browsing, paying for, and publishing Apiosk APIs","directories":{},"_nodeVersion":"24.3.0","dependencies":{"zod":"^4.3.6","viem":"^2.47.0","qrcode":"^1.5.4","express":"^5.2.1","@apiosk/sdk":"^0.1.0","@modelcontextprotocol/sdk":"^1.27.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"ts-node":"^10.9.2","typescript":"^5.9.3","@types/node":"^25.5.0","@types/express":"^5.0.6","@flydotio/dockerfile":"^0.7.10"},"_npmOperationalInternal":{"tmp":"tmp/mcp_1.3.0_1782402940198_0.22650235935310237","host":"s3://npm-registry-packages-npm-production"}},"1.3.1":{"name":"@apiosk/mcp","version":"1.3.1","keywords":["mcp","apiosk","api","model-context-protocol","agent-tools","payments","finance","x402","commerce","crypto"],"author":{"name":"Apiosk"},"license":"MIT","_id":"@apiosk/mcp@1.3.1","maintainers":[{"name":"olivierbrinkman","email":"ollybrinkman@gmail.com"}],"homepage":"https://apiosk.com","bugs":{"url":"https://github.com/obcraft/apiosk-mcp/issues"},"bin":{"apiosk":"index.mjs","apiosk-mcp":"index.mjs","apiosk-mcp-server":"index.mjs"},"dist":{"shasum":"b11f6d054598039a9dc6c79ea57ec251cc52a227","tarball":"https://registry.npmjs.org/@apiosk/mcp/-/mcp-1.3.1.tgz","fileCount":18,"integrity":"sha512-7FlMhgqr8+xqU6OzSYLhz2xphEG3bXE8+248Qb3kD3dl7frF4WI4bBN7Nb9n/NhgiJWvcaTjYuKulpClMoBleA==","signatures":[{"sig":"MEUCIQCV/MzzNvi+RvaEL6iuQQpsMap17ppxWArr2pGdPG3+9QIgOmlfEIqjbO8DSY3t57HguW4B7BcgPp5QVil4Et0oBRY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":238163},"main":"index.mjs","type":"module","engines":{"node":">=20.0.0"},"exports":{".":"./src/create-server.mjs","./runtime":"./src/runtime.mjs","./package.json":"./package.json"},"gitHead":"ea40b11210a4301ae8a9cfa8f2261f8a717e99f7","mcpName":"io.github.obcraft/apiosk-mcp","scripts":{"dev":"node server.mjs","test":"node --test","start":"node server.mjs","test:live":"bash scripts/test-live-url.sh","pack:check":"npm pack --dry-run","smoke:new-env":"bash scripts/smoke-new-env.sh","test:macbook-air":"bash scripts/test-macbook-air.sh"},"_npmUser":{"name":"olivierbrinkman","email":"ollybrinkman@gmail.com"},"repository":{"url":"git+https://github.com/obcraft/apiosk-mcp.git","type":"git"},"_npmVersion":"11.4.2","description":"AI-native payments: discover, pay for, execute, and publish monetized APIs through MCP.","directories":{},"_nodeVersion":"24.3.0","dependencies":{"zod":"^4.3.6","viem":"^2.47.0","qrcode":"^1.5.4","express":"^5.2.1","@apiosk/sdk":"^0.1.0","@modelcontextprotocol/sdk":"^1.27.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"ts-node":"^10.9.2","typescript":"^5.9.3","@types/node":"^25.5.0","@types/express":"^5.0.6","@flydotio/dockerfile":"^0.7.10"},"_npmOperationalInternal":{"tmp":"tmp/mcp_1.3.1_1782841489488_0.17105934237388154","host":"s3://npm-registry-packages-npm-production"}},"1.7.0":{"name":"@apiosk/mcp","version":"1.7.0","keywords":["mcp","apiosk","api","model-context-protocol","agent-tools","payments","finance","x402","commerce","crypto"],"author":{"name":"Apiosk"},"license":"MIT","_id":"@apiosk/mcp@1.7.0","maintainers":[{"name":"olivierbrinkman","email":"ollybrinkman@gmail.com"}],"homepage":"https://apiosk.com","bugs":{"url":"https://github.com/obcraft/apiosk-mcp/issues"},"bin":{"apiosk":"index.mjs","apiosk-mcp":"index.mjs","apiosk-mcp-server":"index.mjs"},"dist":{"shasum":"e6266ca7e8edaa84b275da76fda43474d8e83ced","tarball":"https://registry.npmjs.org/@apiosk/mcp/-/mcp-1.7.0.tgz","fileCount":31,"integrity":"sha512-DNVvRcq5S5XdAXSVTqqeGEMpMyoCpVyWeGb6vG9wI8oTWdCOw5hGu61D9c5evZGl3FJ/ASVHFh8fz/7n5fI/+g==","signatures":[{"sig":"MEYCIQDGd56aiUC8vfB80J49GTh0gnfgYGAiLO95/qk2LThr2QIhAPMaHpdrenFRdXN6G8SJj9d4GeygSjtTwu0Wfg+iiFao","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":3268510},"main":"index.mjs","type":"module","engines":{"node":">=20.0.0"},"exports":{".":"./src/create-server.mjs","./runtime":"./src/runtime.mjs","./package.json":"./package.json"},"gitHead":"5f949ef4d39c80fd94ccadf9165070eb56e39b8c","mcpName":"io.github.obcraft/apiosk-mcp","scripts":{"dev":"node server.mjs","test":"node --test","start":"node server.mjs","test:live":"bash scripts/test-live-url.sh","pack:check":"npm pack --dry-run","smoke:new-env":"bash scripts/smoke-new-env.sh","test:macbook-air":"bash scripts/test-macbook-air.sh"},"_npmUser":{"name":"olivierbrinkman","email":"ollybrinkman@gmail.com"},"repository":{"url":"git+https://github.com/obcraft/apiosk-mcp.git","type":"git"},"_npmVersion":"10.8.2","description":"Discover, pay for, execute, and publish APIs through Apiosk.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"viem":"^2.47.0","qrcode":"^1.5.4","express":"^5.2.1","@apiosk/sdk":"^0.1.0","@modelcontextprotocol/sdk":"^1.27.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"esbuild":"^0.28.1","ts-node":"^10.9.2","typescript":"^5.9.3","@types/node":"^25.5.0","@types/express":"^5.0.6","@flydotio/dockerfile":"^0.7.10","@walletconnect/ethereum-provider":"^2.23.9"},"_npmOperationalInternal":{"tmp":"tmp/mcp_1.7.0_1784725695025_0.14781404560742506","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-06-25T15:55:40.012Z","modified":"2026-08-16T19:44:09.773Z","1.3.0":"2026-06-25T15:55:40.340Z","1.3.1":"2026-06-30T17:44:49.636Z","1.7.0":"2026-07-22T13:08:15.174Z"},"bugs":{"url":"https://github.com/obcraft/apiosk-mcp/issues"},"author":{"name":"Apiosk"},"license":"MIT","homepage":"https://apiosk.com","keywords":["mcp","apiosk","api","model-context-protocol","agent-tools","payments","finance","x402","commerce","crypto"],"repository":{"url":"git+https://github.com/obcraft/apiosk-mcp.git","type":"git"},"description":"Discover, pay for, execute, and publish APIs through Apiosk.","maintainers":[{"email":"ollybrinkman@gmail.com","name":"olivierbrinkman"},{"email":"olivier@apiosk.com","name":"apiosk-packages"}],"readme":"\n
\n \n
\n\n# Apiosk MCP Server\n\n**AI-native payments for tools and APIs.** Discover, pay for, execute, and publish monetized APIs directly from your agent, over USDC/x402 or prepaid credits, through the Model Context Protocol.\n\n`payments` · `finance` · `x402` · `commerce` · `crypto`\n\n[](https://registry.modelcontextprotocol.io)\n[](https://www.npmjs.com/package/@apiosk/mcp)\n[](https://pypi.org/project/apiosk-mcp/)\n[](#license)\n\nOfficial MCP server for discovering, paying for, and publishing Apiosk APIs.\n\n- **Listed in the [official MCP Registry](https://registry.modelcontextprotocol.io)** as `io.github.obcraft/apiosk-mcp`.\n- **Hosted endpoint:** `https://mcp.apiosk.com/mcp` (streamable HTTP, OAuth-protected for paid tools).\n- **Local stdio package:** `npx -y @apiosk/mcp` or `uvx apiosk-mcp` for wallet + publish tools.\n\n## Quick Start\n\n### Package names\n\nThe scoped npm package is the canonical client SDK package:\n\n```bash\nnpm install @apiosk/mcp\n```\n\nIt exposes the same CLI binaries as the legacy package:\n\n```bash\nnpx -y @apiosk/mcp\napiosk-mcp\napiosk-mcp-server\napiosk\n```\n\nThe previous public package name, `apiosk-mcp-server`, remains supported as a\ncompatibility install path for existing MCP client configs.\n\nFor MCP registry submission forms, use:\n\n- npm Package: `@apiosk/mcp`\n- PyPI Package: `apiosk-mcp`\n- Short Description: `Discover, pay for, execute, and publish Apiosk APIs through MCP.`\n\nThe PyPI package is a launcher for the canonical npm package, so `uvx\napiosk-mcp` starts the same MCP server as `npx -y @apiosk/mcp`.\n\n### Local stdio package\n\n```bash\nnpx -y @apiosk/mcp\n```\n\nPython/uv users can install through PyPI:\n\n```bash\nuvx apiosk-mcp\n```\n\nThe PyPI launcher requires Node.js 20+ and `npx` on `PATH`. By default it runs\n`npx -y @apiosk/mcp@1.3.2`; set `APIOSK_MCP_NPM_PACKAGE=@apiosk/mcp@next` to\noverride the npm package spec.\n\n### Publishing packages\n\nFrom this `mcp/` directory:\n\n```bash\nnpm run pack:check\nnpm publish --access public\n```\n\n```bash\npython3 -m pip install --upgrade build twine\npython3 -m build\npython3 -m twine upload dist/apiosk_mcp-1.3.2*\n```\n\nAfter both uploads are live, the MCP registry package fields are:\n\n```text\nnpm Package: @apiosk/mcp\nPyPI Package: apiosk-mcp\nShort Description: Discover, pay for, execute, and publish Apiosk APIs through MCP.\n```\n\n### With automatic x402 payments from an env wallet\n\n```bash\nAPIOSK_PRIVATE_KEY=0x... npx -y @apiosk/mcp\n```\n\n### With dashboard-managed access\n\n```bash\nAPIOSK_CONNECT_TOKEN=... npx -y @apiosk/mcp\n```\n\nAfter the MCP server is installed in Claude, Codex, or another client, the fastest first-run path in local stdio mode is:\n\n```json\n{ \"wallet_label\": \"My Apiosk wallet\" }\n```\n\nCall that through `apiosk_get_started`. It will create a local wallet when needed, or you can pass `connect_string` to save managed access locally and immediately run a discovery probe plus a small test call.\n\n## Local Wallet Mode\n\nThe local stdio package exposes wallet tools that let Claude or Codex:\n\n- create or import a wallet\n- show the wallet address\n- select the active wallet used for paid calls\n- reveal or save the private key when the user explicitly asks\n- publish and manage APIs without opening the dashboard\n\nThe active wallet is mirrored to:\n\n- `~/.apiosk/wallet.json`\n- `~/.apiosk/wallet.txt`\n\nso older Apiosk scripts can reuse it.\n\n## Agent Configuration\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"apiosk\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@apiosk/mcp\"]\n }\n }\n}\n```\n\n### VS Code\n\nAdd the server with the CLI:\n\n```bash\ncode --add-mcp '{\"name\":\"apiosk\",\"command\":\"npx\",\"args\":[\"-y\",\"@apiosk/mcp\"]}'\n```\n\nOr create `.vscode/mcp.json` in your workspace (VS Code uses a `servers` key):\n\n```json\n{\n \"servers\": {\n \"apiosk\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@apiosk/mcp\"]\n }\n }\n}\n```\n\nTo use the hosted endpoint instead of the local package:\n\n```json\n{\n \"servers\": {\n \"apiosk\": {\n \"type\": \"http\",\n \"url\": \"https://mcp.apiosk.com/mcp\"\n }\n }\n}\n```\n\n### Cursor\n\n```json\n{\n \"mcpServers\": {\n \"apiosk\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@apiosk/mcp\"]\n }\n }\n}\n```\n\n### Windsurf\n\n```json\n{\n \"mcpServers\": {\n \"apiosk\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@apiosk/mcp\"]\n }\n }\n}\n```\n\n### Claude Code\n\nRemote HTTP:\n\n```bash\nclaude mcp add --transport http apiosk https://mcp.apiosk.com/mcp\n```\n\nLocal stdio:\n\n```json\n{\n \"mcpServers\": {\n \"apiosk\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@apiosk/mcp\"]\n }\n }\n}\n```\n\n### Cline / Continue / Goose\n\n```json\n{\n \"mcpServers\": {\n \"apiosk\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@apiosk/mcp\"]\n }\n }\n}\n```\n\n### Using a local checkout\n\n```json\n{\n \"mcpServers\": {\n \"apiosk\": {\n \"command\": \"node\",\n \"args\": [\"/full/path/to/apiosk-mcp/index.mjs\"]\n }\n }\n}\n```\n\n### ChatGPT and other remote MCP apps\n\nUse the hosted MCP endpoint:\n\n```text\nhttps://mcp.apiosk.com/mcp\n```\n\nProtected tools on the hosted server use OAuth. The remote MCP surface is fully\ncapable, discovery, payment guidance, generic **and** dynamic per-API\nexecution, prepaid credits, and managed agent-wallet CRUD. Public tools\n(discovery + guidance) work before authorization; paid execution and managed\ntools require OAuth. Publishing stays local/portal-only because it needs a\nclient-side signing key the hosted server never holds.\n\n## Provider MCP Monetization\n\nIf you own an MCP server and want to sell its tools through Apiosk, keep payment\nlogic out of your MCP. Apiosk is the paid edge.\n\nProvider requirements:\n\n- Host your MCP over HTTPS, for example `https://tools.example.com/mcp`.\n- Support normal MCP `initialize`, `tools/list`, and `tools/call`.\n- Keep tool names stable; imported tools become paid operation ids.\n- Provide useful descriptions and JSON schemas; these become buyer-facing\n discovery metadata.\n- Protect the provider MCP with bearer auth or another upstream secret, then\n configure Apiosk to inject that secret so buyers cannot bypass the gateway.\n\nProvider portal flow:\n\n1. Open the provider portal and choose `Import MCP`.\n2. Enter the MCP URL and optional bearer token.\n3. Apiosk scans `tools/list` and creates one paid action per selected tool.\n4. Review tool paths, schemas, descriptions, and per-call prices.\n5. Publish the draft after linking a payout wallet.\n\nBuyer-facing surfaces after publish:\n\n- Hosted Apiosk MCP: `https://mcp.apiosk.com/mcp`\n- Catalog search: `https://gateway.apiosk.com/v1/apis?search=`\n- Metadata: `GET https://gateway.apiosk.com//metadata`\n- Execution: `POST https://gateway.apiosk.com//execute`\n\nThe traffic path is:\n\n```text\nbuyer agent -> Apiosk MCP/gateway -> payment rail -> provider MCP tools/call\n```\n\nThe provider MCP should reject direct unauthenticated traffic, but it should not\nreturn `402 Payment Required` or inspect `X-Payment`. Payment challenges,\ncredits, x402 proof verification, and revenue splits are handled by Apiosk.\n\n## Publish Paid x402 Routes from a Coding Agent\n\nThe hosted MCP doubles as a **publisher** for coding agents (Claude Code,\nCursor, Codex, and friends): build an API, then publish it as a paid x402\nendpoint on the Apiosk gateway in one tool call.\n\nAuthenticate with an Apiosk **provider API key** (`sk_live_…`, minted in the\nprovider portal under Settings → API keys):\n\n```json\n{\n \"mcpServers\": {\n \"apiosk\": {\n \"url\": \"https://mcp.apiosk.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer sk_live_YOUR_PROVIDER_KEY\"\n }\n }\n }\n}\n```\n\nTools:\n\n- `publish_x402_route`: create a paid route: name, `upstream_url`, `price`\n (USDC per call), `settlement_address`, optional `method`/`path`/schemas/tags.\n Returns the `paid_url` on `gateway.apiosk.com` plus the route's status.\n- `list_x402_routes`: all your routes with paid URLs, prices, and status.\n- `update_x402_route`: change price, description, upstream URL, schemas,\n settlement address, or status.\n- `unpublish_x402_route`: disable a route (reversible).\n- `test_x402_route`: fire an unpaid request at the paid URL and verify it\n returns `402 Payment Required` with a valid x402 `accepts[]` offer.\n- `generate_openapi_spec`: host an OpenAPI 3.1 spec for the route at\n `https://mcp.apiosk.com/openapi/.json`.\n- `publish_project`: publish several routes of one project in a single call.\n\nLifecycle: new routes land in Apiosk's operator review queue\n(`status: \"pending_review\"`). On approval they serve x402 payments, appear in\n`https://gateway.apiosk.com/.well-known/x402`, and are auto-indexed in the\nCoinbase x402 Bazaar. Settlement pays 98% of each call to your\n`settlement_address` (Apiosk keeps a 2% platform fee).\n\nDiscovery endpoints for machines:\n\n- `https://mcp.apiosk.com/.well-known/apiosk-routes.json` (alias `/discovery`)\n , machine-readable index of every paid route on the gateway.\n- `https://mcp.apiosk.com/openapi/.json`: per-route OpenAPI spec.\n\nLocal stdio use: set `APIOSK_PROVIDER_TOKEN=sk_live_…` instead of the header.\nHosted server operators must configure `APIOSK_SUPABASE_SERVICE_ROLE_KEY` (the\ntools verify provider keys and write listings through the gateway database).\n\n## Available Tools\n\nStatic tools:\n\n- `apiosk_help`\n- `apiosk_payment_guide`: buyer + provider guide for paying through and publishing on the gateway\n- `apiosk_explore`\n- `apiosk_search`\n- `apiosk_discover`\n- `apiosk_inspect_x402`\n- `apiosk_fetch_paid`\n- `apiosk_get_api`\n- `apiosk_execute`\n\n`apiosk_search` also returns matching x402 discovery sources in `sources`, even\nwhen the Apiosk API catalog has no listing with that name. Each source includes\nits direct REST/MCP endpoints and marks paid endpoints with\n`payment_required`, `price_usdc`, and `executable_via`. `apiosk_discover` can\nquery the wired free sources directly; paid discovery sources such as x402scan\nand Apify are returned as `apiosk_inspect_x402` → `apiosk_fetch_paid` pointers\nand are never paid automatically.\n\nHosted remote MCP tools (in addition to dynamic per-API tools):\n\n- Discovery / guidance: `apiosk_help`, `apiosk_payment_guide`, `apiosk_search`, `apiosk_explore`, `apiosk_discover`, `apiosk_inspect_x402`, `apiosk_get_api`, `apiosk_metadata`, `apiosk_execute`, `apiosk_health`\n- External paid fetch: `apiosk_fetch_paid` (OAuth/connect-token protected; requires explicit live-price confirmation)\n- Prepaid credits: `apiosk_buy_credits`, `apiosk_get_credits_status`\n- Managed wallets: `apiosk_list_wallets`, `apiosk_create_wallet`, `apiosk_update_wallet`, `apiosk_delete_wallet`, `apiosk_get_wallet_activity`, `apiosk_create_wallet_connect_string`, `apiosk_list_wallet_api_keys`, `apiosk_create_wallet_api_key`, `apiosk_update_wallet_api_key`, `apiosk_delete_wallet_api_key`\n\nLocal wallet tools in stdio mode:\n\n- `apiosk_get_started`\n- `apiosk_wallet_list`\n- `apiosk_wallet_create`\n- `apiosk_configure`\n- `apiosk_wallet_select`\n- `apiosk_wallet_update`\n- `apiosk_wallet_delete`\n- `apiosk_wallet_reveal_secret`\n- `apiosk_wallet_save_secret`\n\nPublish tools in stdio mode:\n\n- `apiosk_publish_api`\n- `apiosk_list_my_apis`\n- `apiosk_update_api`\n- `apiosk_delete_api`\n\nx402 publisher tools (all modes, provider-token auth):\n\n- `publish_x402_route`\n- `list_x402_routes`\n- `update_x402_route`\n- `unpublish_x402_route`\n- `test_x402_route`\n- `generate_openapi_spec`\n- `publish_project`\n\nOptional dashboard-managed wallet tools:\n\n- `apiosk_list_wallets`\n- `apiosk_create_wallet`\n- `apiosk_update_wallet`\n- `apiosk_delete_wallet`\n- `apiosk_get_wallet_activity`\n- `apiosk_create_wallet_connect_string`\n- `apiosk_list_wallet_api_keys`\n- `apiosk_create_wallet_api_key`\n- `apiosk_update_wallet_api_key`\n- `apiosk_delete_wallet_api_key`\n\nDynamic tools:\n\n- local stdio mode still generates one dynamic tool per active Apiosk API slug from listing metadata\n\n## Examples\n\n### Explore\n\n```json\n{}\n```\n\n```json\n{ \"listing_type\": \"dataset\", \"search\": \"weather\", \"limit\": 5 }\n```\n\n### Search\n\n```json\n{ \"search\": \"diff\", \"limit\": 5 }\n```\n\nSearch, explore, and `apiosk_get_api` responses now embed a `payment` block that\ntells the agent exactly how to settle a paid call given the current auth, so an\nagent that finds, say, a weather API immediately knows whether it can pay and\nwhat to do next.\n\n### Payment guide (buyer + provider)\n\n```json\n{}\n```\n\n```json\n{ \"role\": \"provider\" }\n```\n\n```json\n{ \"role\": \"buyer\", \"slug\": \"weather-now\" }\n```\n\nReturns a buyer guide (USDC/x402 or credits, tailored to the configured auth)\nand a provider guide (how to publish an API and get paid). Pass `slug` to scope\nbuyer guidance to one listing, or `role` to pick a side.\n\n### Create a local wallet\n\n```json\n{ \"label\": \"Claude wallet\" }\n```\n\nThe create response includes:\n\n- the wallet address\n- Base funding instructions\n- a QR image URL\n- a terminal QR block when QR rendering is enabled\n- a structured Apiosk control menu with wallet, funding, pay, publish, security, and local-data sections\n\n### Get started in one step\n\nCreate a local wallet automatically, discover the catalog, and run a test call:\n\n```json\n{\n \"wallet_label\": \"Starter wallet\",\n \"test_slug\": \"agent-json-diff\",\n \"test_input\": {\n \"before\": { \"ok\": true },\n \"after\": { \"ok\": false }\n }\n}\n```\n\nOr save a dashboard-managed connect string locally and verify it:\n\n```json\n{\n \"connect_string\": \"export APIO_GATEWAY_URL=https://gateway.apiosk.com\\nexport APIO_CHAIN_ID=8453\\nexport APIO_AGENT_WALLET_ADDRESS=0x...\\nexport APIO_CONNECT_TOKEN=aw_...\\nexport APIO_CONNECT_AUTHORIZATION=Bearer aw_...\\nexport APIO_CONNECT_HEADER_NAME=X-Apiosk-Connect-Token\",\n \"test_slug\": \"agent-json-diff\",\n \"test_input\": {\n \"before\": { \"ok\": true },\n \"after\": { \"ok\": false }\n },\n \"create_wallet\": false\n}\n```\n\nThe connect string identifies the buyer's managed wallet and connect token. The\n`APIO_WALLET_*` limits bound the USDC (x402) rail. The same connect token also\nsettles over prepaid credits when USDC is unavailable, the gateway picks the\nrail per call. Call `apiosk_help` with `topic=\"rails\"` for the full settlement\nmodel.\n\n### Open the configure menu\n\n```json\n{ \"section\": \"funding\" }\n```\n\n```json\n{ \"wallet_id\": \"...\", \"section\": \"funding\", \"funding_provider\": \"onramper\" }\n```\n\n### Save a secret key backup\n\n```json\n{ \"wallet_id\": \"...\" }\n```\n\n### Publish an API\n\n```json\n{\n \"name\": \"My Weather API\",\n \"slug\": \"my-weather-api\",\n \"endpoint_url\": \"https://example.com\",\n \"price_usd\": 0.01,\n \"description\": \"Real-time weather data\",\n \"listing_group\": \"datasets\"\n}\n```\n\n### Generic execute\n\n```json\n{\n \"slug\": \"agent-json-diff\",\n \"input\": {\n \"before\": { \"ok\": true },\n \"after\": { \"ok\": false }\n }\n}\n```\n\n### Dynamic tool call (local stdio only)\n\nIf the server lists a dynamic tool named `agent-json-diff`, call it directly:\n\n```json\n{\n \"before\": { \"ok\": true },\n \"after\": { \"ok\": false }\n}\n```\n\n## MacBook Air Test Script\n\nRun the safe default suite from a repo checkout:\n\n```bash\ncd /Users/olivierbrinkman/Development/Apiosk/subs/mcp\nnpm run test:macbook-air\n```\n\nDefault coverage:\n\n- runs `npm test`\n- runs the isolated fresh-environment smoke test\n- starts a local HTTP MCP server in a temp `APIOSK_HOME`\n- verifies `health`, `tools/list`, `apiosk_search`, `apiosk_explore`, and `apiosk_get_api`\n- creates a wallet, checks funding QR/configure output, and verifies secret export plus `wallet.json` and `wallet.txt`\n- verifies the hosted Fly deployment, OAuth metadata, protected-resource metadata, public discovery, and the unauthenticated OAuth challenge for protected tools\n\nUseful options:\n\n- `TARGET=local` to skip hosted checks\n- `TARGET=hosted` to skip local checks\n- `APIOSK_RUN_REMOTE_WALLET_TEST=1 APIOSK_MCP_BEARER_TOKEN=...` to verify an authenticated protected hosted call after the unauthenticated challenge check\n- `APIOSK_RUN_FUNDED_TESTS=1 APIOSK_TEST_PRIVATE_KEY=0x...` to import a funded wallet and run a real paid execute test\n- `APIOSK_RUN_FUNDED_TESTS=1 APIOSK_MCP_BEARER_TOKEN=... TARGET=hosted` to run a real paid execute test through the hosted OAuth path\n- `APIOSK_RUN_FUNDED_TESTS=1 APIOSK_RUN_PUBLISH_TEST=1 APIOSK_TEST_PRIVATE_KEY=0x... TARGET=local` to also test publish, list, update, and delete with a temporary listing\n\nExample funded run:\n\n```bash\ncd /Users/olivierbrinkman/Development/Apiosk/subs/mcp\nAPIOSK_RUN_FUNDED_TESTS=1 \\\nAPIOSK_TEST_PRIVATE_KEY=0x... \\\nnpm run test:macbook-air\n```\n\n## Live URL Test Script\n\nRun a hosted-only test directly against the public MCP endpoint:\n\n```bash\ncd /Users/olivierbrinkman/Development/Apiosk/subs/mcp\nnpm run test:live\n```\n\nDefault live coverage:\n\n- checks `https://mcp.apiosk.com/health`\n- verifies the hosted tool surface\n- verifies `/.well-known/oauth-authorization-server`\n- verifies `/.well-known/oauth-protected-resource/mcp`\n- runs live `apiosk_explore`, `apiosk_metadata`, and `apiosk_health`\n- verifies that an unauthenticated protected MCP tool call returns the expected OAuth `401` challenge\n\nOptional live funded checks:\n\n- `APIOSK_RUN_REMOTE_WALLET_TEST=1 APIOSK_MCP_BEARER_TOKEN=... npm run test:live`\n- `APIOSK_RUN_FUNDED_TESTS=1 APIOSK_MCP_BEARER_TOKEN=... npm run test:live`\n\nThe live hosted suite no longer imports a private key into the hosted MCP. Protected live checks now rely on a real hosted OAuth bearer token, which matches the ChatGPT-style remote MCP flow.\n\n## Environment Variables\n\n- `APIOSK_PRIVATE_KEY`: enables automatic x402 settlement and signed publish requests\n- `APIOSK_CONNECT_TOKEN`: attach a dashboard-managed connect token\n- `APIOSK_CONNECT_AUTHORIZATION`: attach a custom Authorization header\n- `APIOSK_CONNECT_HEADER_NAME`: override the connect-token header name\n- `APIOSK_WALLET_ADDRESS`: send a wallet address for wallet-aware flows\n- `APIOSK_X_PAYMENT`: attach a pre-built x402 proof manually\n- `APIOSK_GATEWAY`: override the gateway base URL\n- `APIOSK_CONTROL_PLANE_URL`: override the MCP-owned control-plane API base URL used for account, credits, and managed-wallet routes. Defaults to `https://mcp.apiosk.com`\n- `APIOSK_DASHBOARD_URL`: override the human-facing dashboard/app URL stored in local config and used in confirmation flows. Defaults to `https://dashboard.apiosk.com`\n- `APIOSK_DASHBOARD_JWT` or `APIOSK_USER_JWT`: unlock dashboard wallet routes\n- `APIOSK_ENABLE_LOCAL_WALLETS=true`: enable local wallet tools in HTTP server mode\n- `APIOSK_MCP_OAUTH_SECRET` or `APIOSK_MCP_AUTH_SECRET`: signing secret for hosted OAuth codes, access tokens, and refresh tokens\n- `APIOSK_MCP_BEARER_TOKEN`: optional hosted OAuth access token used by the live scripts for authenticated protected-tool checks\n- `APIOSK_HOME`: override the default `~/.apiosk` directory\n- `APIOSK_MCP_WALLET_STORE`: override the local wallet store path\n\n## Human-Funded Credits Flow\n\nIn the local stdio package, MCP can now help a human top up Apiosk credits and then let the agent spend those credits later:\n\n1. `apiosk_create_account` if the user needs a new Apiosk account\n2. `apiosk_sign_in` to store a local dashboard session token\n3. `apiosk_buy_credits` to create an Adyen checkout link\n4. `apiosk_get_credits_status` after payment to reconcile the top-up and confirm the balance\n\nIf signup does not return a session immediately, tell the user to confirm their email first and then call `apiosk_sign_in`.\n\nThese calls now target the MCP-owned control-plane surface by default:\n\n- `https://mcp.apiosk.com/api/auth/mcp-sign-up`\n- `https://mcp.apiosk.com/api/auth/mcp-sign-in`\n- `https://mcp.apiosk.com/api/credits/topup`\n- `https://mcp.apiosk.com/api/credits/reconcile`\n\n## Remote HTTP Server\n\nThe public HTTP deployment is safe-by-default: local wallet and publish tools are disabled unless `APIOSK_ENABLE_LOCAL_WALLETS=true` is set on that server.\n\nHosted OAuth metadata and authorization routes now live on the same host:\n\n- `https://mcp.apiosk.com/.well-known/oauth-authorization-server`\n- `https://mcp.apiosk.com/.well-known/oauth-protected-resource/mcp`\n- `https://mcp.apiosk.com/authorize`\n- `https://mcp.apiosk.com/token`\n- `https://mcp.apiosk.com/register`\n\nTest it:\n\n```bash\ncurl https://mcp.apiosk.com/health\n```\n\n```bash\ncurl https://mcp.apiosk.com/mcp \\\n -H \"Content-Type: application/json\" \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}'\n```\n\n## Development\n\n```bash\nnpm install\nnpm run dev # HTTP server on :3000\nnode index.mjs # stdio mode with local wallet tools enabled\n```\n\nFresh-environment smoke test:\n\n```bash\ncd /Users/olivierbrinkman/Development/Apiosk/subs/mcp\nnpm run smoke:new-env\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}
![\"Apiosk\"](\"https://apiosk.com/logo.svg\"){kind=logo}
\n