@apiosk/mcp 1.3.0

package/README.md

@@ -0,0 +1,590 @@
+# Apiosk MCP Server
+
+Official MCP server for discovering, paying for, and publishing Apiosk APIs.
+
+## Quick Start
+
+### Package names
+
+The scoped npm package is the canonical client SDK package:
+
+```bash
+npm install @apiosk/mcp
+```
+
+It exposes the same CLI binaries as the legacy package:
+
+```bash
+npx -y @apiosk/mcp
+apiosk-mcp
+apiosk-mcp-server
+apiosk
+```
+
+The previous public package name, `apiosk-mcp-server`, remains supported as a
+compatibility install path for existing MCP client configs.
+
+For MCP registry submission forms, use:
+
+- npm Package: `@apiosk/mcp`
+- PyPI Package: `apiosk-mcp`
+- Short Description: `Discover, pay for, execute, and publish Apiosk APIs through MCP.`
+
+The PyPI package is a launcher for the canonical npm package, so `uvx
+apiosk-mcp` starts the same MCP server as `npx -y @apiosk/mcp`.
+
+### Local stdio package
+
+```bash
+npx -y @apiosk/mcp
+```
+
+Python/uv users can install through PyPI:
+
+```bash
+uvx apiosk-mcp
+```
+
+The PyPI launcher requires Node.js 20+ and `npx` on `PATH`. By default it runs
+`npx -y @apiosk/mcp@1.3.0`; set `APIOSK_MCP_NPM_PACKAGE=@apiosk/mcp@next` to
+override the npm package spec.
+
+### Publishing packages
+
+From this `mcp/` directory:
+
+```bash
+npm run pack:check
+npm publish --access public
+```
+
+```bash
+python3 -m pip install --upgrade build twine
+python3 -m build
+python3 -m twine upload dist/apiosk_mcp-1.3.0*
+```
+
+After both uploads are live, the MCP registry package fields are:
+
+```text
+npm Package: @apiosk/mcp
+PyPI Package: apiosk-mcp
+Short Description: Discover, pay for, execute, and publish Apiosk APIs through MCP.
+```
+
+### With automatic x402 payments from an env wallet
+
+```bash
+APIOSK_PRIVATE_KEY=0x... npx -y @apiosk/mcp
+```
+
+### With dashboard-managed access
+
+```bash
+APIOSK_CONNECT_TOKEN=... npx -y @apiosk/mcp
+```
+
+After the MCP server is installed in Claude, Codex, or another client, the fastest first-run path in local stdio mode is:
+
+```json
+{ "wallet_label": "My Apiosk wallet" }
+```
+
+Call 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.
+
+## Local Wallet Mode
+
+The local stdio package exposes wallet tools that let Claude or Codex:
+
+- create or import a wallet
+- show the wallet address
+- select the active wallet used for paid calls
+- reveal or save the private key when the user explicitly asks
+- publish and manage APIs without opening the dashboard
+
+The active wallet is mirrored to:
+
+- `~/.apiosk/wallet.json`
+- `~/.apiosk/wallet.txt`
+
+so older Apiosk scripts can reuse it.
+
+## Agent Configuration
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "apiosk": {
+      "command": "npx",
+      "args": ["-y", "@apiosk/mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+```json
+{
+  "mcpServers": {
+    "apiosk": {
+      "command": "npx",
+      "args": ["-y", "@apiosk/mcp"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+```json
+{
+  "mcpServers": {
+    "apiosk": {
+      "command": "npx",
+      "args": ["-y", "@apiosk/mcp"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+Remote HTTP:
+
+```bash
+claude mcp add --transport http apiosk https://mcp.apiosk.com/mcp
+```
+
+Local stdio:
+
+```json
+{
+  "mcpServers": {
+    "apiosk": {
+      "command": "npx",
+      "args": ["-y", "@apiosk/mcp"]
+    }
+  }
+}
+```
+
+### Cline / Continue / Goose
+
+```json
+{
+  "mcpServers": {
+    "apiosk": {
+      "command": "npx",
+      "args": ["-y", "@apiosk/mcp"]
+    }
+  }
+}
+```
+
+### Using a local checkout
+
+```json
+{
+  "mcpServers": {
+    "apiosk": {
+      "command": "node",
+      "args": ["/full/path/to/apiosk-mcp/index.mjs"]
+    }
+  }
+}
+```
+
+### ChatGPT and other remote MCP apps
+
+Use the hosted MCP endpoint:
+
+```text
+https://mcp.apiosk.com/mcp
+```
+
+Protected tools on the hosted server use OAuth. The remote MCP surface is fully
+capable — discovery, payment guidance, generic **and** dynamic per-API
+execution, prepaid credits, and managed agent-wallet CRUD. Public tools
+(discovery + guidance) work before authorization; paid execution and managed
+tools require OAuth. Publishing stays local/portal-only because it needs a
+client-side signing key the hosted server never holds.
+
+## Provider MCP Monetization
+
+If you own an MCP server and want to sell its tools through Apiosk, keep payment
+logic out of your MCP. Apiosk is the paid edge.
+
+Provider requirements:
+
+- Host your MCP over HTTPS, for example `https://tools.example.com/mcp`.
+- Support normal MCP `initialize`, `tools/list`, and `tools/call`.
+- Keep tool names stable; imported tools become paid operation ids.
+- Provide useful descriptions and JSON schemas; these become buyer-facing
+  discovery metadata.
+- Protect the provider MCP with bearer auth or another upstream secret, then
+  configure Apiosk to inject that secret so buyers cannot bypass the gateway.
+
+Provider portal flow:
+
+1. Open the provider portal and choose `Import MCP`.
+2. Enter the MCP URL and optional bearer token.
+3. Apiosk scans `tools/list` and creates one paid action per selected tool.
+4. Review tool paths, schemas, descriptions, and per-call prices.
+5. Publish the draft after linking a payout wallet.
+
+Buyer-facing surfaces after publish:
+
+- Hosted Apiosk MCP: `https://mcp.apiosk.com/mcp`
+- Catalog search: `https://gateway.apiosk.com/v1/apis?search=<slug>`
+- Metadata: `GET https://gateway.apiosk.com/<slug>/metadata`
+- Execution: `POST https://gateway.apiosk.com/<slug>/execute`
+
+The traffic path is:
+
+```text
+buyer agent -> Apiosk MCP/gateway -> payment rail -> provider MCP tools/call
+```
+
+The provider MCP should reject direct unauthenticated traffic, but it should not
+return `402 Payment Required` or inspect `X-Payment`. Payment challenges,
+credits, x402 proof verification, and revenue splits are handled by Apiosk.
+
+## Available Tools
+
+Static tools:
+
+- `apiosk_help`
+- `apiosk_payment_guide` — buyer + provider guide for paying through and publishing on the gateway
+- `apiosk_explore`
+- `apiosk_search`
+- `apiosk_get_api`
+- `apiosk_execute`
+
+Hosted remote MCP tools (in addition to dynamic per-API tools):
+
+- Discovery / guidance: `apiosk_help`, `apiosk_payment_guide`, `apiosk_search`, `apiosk_explore`, `apiosk_get_api`, `apiosk_metadata`, `apiosk_execute`, `apiosk_health`
+- Prepaid credits: `apiosk_buy_credits`, `apiosk_get_credits_status`
+- 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`
+
+Local wallet tools in stdio mode:
+
+- `apiosk_get_started`
+- `apiosk_wallet_list`
+- `apiosk_wallet_create`
+- `apiosk_configure`
+- `apiosk_wallet_select`
+- `apiosk_wallet_update`
+- `apiosk_wallet_delete`
+- `apiosk_wallet_reveal_secret`
+- `apiosk_wallet_save_secret`
+
+Publish tools in stdio mode:
+
+- `apiosk_publish_api`
+- `apiosk_list_my_apis`
+- `apiosk_update_api`
+- `apiosk_delete_api`
+
+Optional dashboard-managed wallet tools:
+
+- `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`
+
+Dynamic tools:
+
+- local stdio mode still generates one dynamic tool per active Apiosk API slug from listing metadata
+
+## Examples
+
+### Explore
+
+```json
+{}
+```
+
+```json
+{ "listing_type": "dataset", "search": "weather", "limit": 5 }
+```
+
+### Search
+
+```json
+{ "search": "diff", "limit": 5 }
+```
+
+Search, explore, and `apiosk_get_api` responses now embed a `payment` block that
+tells the agent exactly how to settle a paid call given the current auth — so an
+agent that finds, say, a weather API immediately knows whether it can pay and
+what to do next.
+
+### Payment guide (buyer + provider)
+
+```json
+{}
+```
+
+```json
+{ "role": "provider" }
+```
+
+```json
+{ "role": "buyer", "slug": "weather-now" }
+```
+
+Returns a buyer guide (USDC/x402 or credits — tailored to the configured auth)
+and a provider guide (how to publish an API and get paid). Pass `slug` to scope
+buyer guidance to one listing, or `role` to pick a side.
+
+### Create a local wallet
+
+```json
+{ "label": "Claude wallet" }
+```
+
+The create response includes:
+
+- the wallet address
+- Base funding instructions
+- a QR image URL
+- a terminal QR block when QR rendering is enabled
+- a structured Apiosk control menu with wallet, funding, pay, publish, security, and local-data sections
+
+### Get started in one step
+
+Create a local wallet automatically, discover the catalog, and run a test call:
+
+```json
+{
+  "wallet_label": "Starter wallet",
+  "test_slug": "agent-json-diff",
+  "test_input": {
+    "before": { "ok": true },
+    "after": { "ok": false }
+  }
+}
+```
+
+Or save a dashboard-managed connect string locally and verify it:
+
+```json
+{
+  "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",
+  "test_slug": "agent-json-diff",
+  "test_input": {
+    "before": { "ok": true },
+    "after": { "ok": false }
+  },
+  "create_wallet": false
+}
+```
+
+The connect string identifies the buyer's managed wallet and connect token. The
+`APIO_WALLET_*` limits bound the USDC (x402) rail. The same connect token also
+settles over prepaid credits when USDC is unavailable — the gateway picks the
+rail per call. Call `apiosk_help` with `topic="rails"` for the full settlement
+model.
+
+### Open the configure menu
+
+```json
+{ "section": "funding" }
+```
+
+```json
+{ "wallet_id": "...", "section": "funding", "funding_provider": "onramper" }
+```
+
+### Save a secret key backup
+
+```json
+{ "wallet_id": "..." }
+```
+
+### Publish an API
+
+```json
+{
+  "name": "My Weather API",
+  "slug": "my-weather-api",
+  "endpoint_url": "https://example.com",
+  "price_usd": 0.01,
+  "description": "Real-time weather data",
+  "listing_group": "datasets"
+}
+```
+
+### Generic execute
+
+```json
+{
+  "slug": "agent-json-diff",
+  "input": {
+    "before": { "ok": true },
+    "after": { "ok": false }
+  }
+}
+```
+
+### Dynamic tool call (local stdio only)
+
+If the server lists a dynamic tool named `agent-json-diff`, call it directly:
+
+```json
+{
+  "before": { "ok": true },
+  "after": { "ok": false }
+}
+```
+
+## MacBook Air Test Script
+
+Run the safe default suite from a repo checkout:
+
+```bash
+cd /Users/olivierbrinkman/Development/Apiosk/subs/mcp
+npm run test:macbook-air
+```
+
+Default coverage:
+
+- runs `npm test`
+- runs the isolated fresh-environment smoke test
+- starts a local HTTP MCP server in a temp `APIOSK_HOME`
+- verifies `health`, `tools/list`, `apiosk_search`, `apiosk_explore`, and `apiosk_get_api`
+- creates a wallet, checks funding QR/configure output, and verifies secret export plus `wallet.json` and `wallet.txt`
+- verifies the hosted Fly deployment, OAuth metadata, protected-resource metadata, public discovery, and the unauthenticated OAuth challenge for protected tools
+
+Useful options:
+
+- `TARGET=local` to skip hosted checks
+- `TARGET=hosted` to skip local checks
+- `APIOSK_RUN_REMOTE_WALLET_TEST=1 APIOSK_MCP_BEARER_TOKEN=...` to verify an authenticated protected hosted call after the unauthenticated challenge check
+- `APIOSK_RUN_FUNDED_TESTS=1 APIOSK_TEST_PRIVATE_KEY=0x...` to import a funded wallet and run a real paid execute test
+- `APIOSK_RUN_FUNDED_TESTS=1 APIOSK_MCP_BEARER_TOKEN=... TARGET=hosted` to run a real paid execute test through the hosted OAuth path
+- `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
+
+Example funded run:
+
+```bash
+cd /Users/olivierbrinkman/Development/Apiosk/subs/mcp
+APIOSK_RUN_FUNDED_TESTS=1 \
+APIOSK_TEST_PRIVATE_KEY=0x... \
+npm run test:macbook-air
+```
+
+## Live URL Test Script
+
+Run a hosted-only test directly against the public MCP endpoint:
+
+```bash
+cd /Users/olivierbrinkman/Development/Apiosk/subs/mcp
+npm run test:live
+```
+
+Default live coverage:
+
+- checks `https://mcp.apiosk.com/health`
+- verifies the hosted tool surface
+- verifies `/.well-known/oauth-authorization-server`
+- verifies `/.well-known/oauth-protected-resource/mcp`
+- runs live `apiosk_explore`, `apiosk_metadata`, and `apiosk_health`
+- verifies that an unauthenticated protected MCP tool call returns the expected OAuth `401` challenge
+
+Optional live funded checks:
+
+- `APIOSK_RUN_REMOTE_WALLET_TEST=1 APIOSK_MCP_BEARER_TOKEN=... npm run test:live`
+- `APIOSK_RUN_FUNDED_TESTS=1 APIOSK_MCP_BEARER_TOKEN=... npm run test:live`
+
+The 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.
+
+## Environment Variables
+
+- `APIOSK_PRIVATE_KEY`: enables automatic x402 settlement and signed publish requests
+- `APIOSK_CONNECT_TOKEN`: attach a dashboard-managed connect token
+- `APIOSK_CONNECT_AUTHORIZATION`: attach a custom Authorization header
+- `APIOSK_CONNECT_HEADER_NAME`: override the connect-token header name
+- `APIOSK_WALLET_ADDRESS`: send a wallet address for wallet-aware flows
+- `APIOSK_X_PAYMENT`: attach a pre-built x402 proof manually
+- `APIOSK_GATEWAY`: override the gateway base URL
+- `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`
+- `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`
+- `APIOSK_DASHBOARD_JWT` or `APIOSK_USER_JWT`: unlock dashboard wallet routes
+- `APIOSK_ENABLE_LOCAL_WALLETS=true`: enable local wallet tools in HTTP server mode
+- `APIOSK_MCP_OAUTH_SECRET` or `APIOSK_MCP_AUTH_SECRET`: signing secret for hosted OAuth codes, access tokens, and refresh tokens
+- `APIOSK_MCP_BEARER_TOKEN`: optional hosted OAuth access token used by the live scripts for authenticated protected-tool checks
+- `APIOSK_HOME`: override the default `~/.apiosk` directory
+- `APIOSK_MCP_WALLET_STORE`: override the local wallet store path
+
+## Human-Funded Credits Flow
+
+In the local stdio package, MCP can now help a human top up Apiosk credits and then let the agent spend those credits later:
+
+1. `apiosk_create_account` if the user needs a new Apiosk account
+2. `apiosk_sign_in` to store a local dashboard session token
+3. `apiosk_buy_credits` to create an Adyen checkout link
+4. `apiosk_get_credits_status` after payment to reconcile the top-up and confirm the balance
+
+If signup does not return a session immediately, tell the user to confirm their email first and then call `apiosk_sign_in`.
+
+These calls now target the MCP-owned control-plane surface by default:
+
+- `https://mcp.apiosk.com/api/auth/mcp-sign-up`
+- `https://mcp.apiosk.com/api/auth/mcp-sign-in`
+- `https://mcp.apiosk.com/api/credits/topup`
+- `https://mcp.apiosk.com/api/credits/reconcile`
+
+## Remote HTTP Server
+
+The 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.
+
+Hosted OAuth metadata and authorization routes now live on the same host:
+
+- `https://mcp.apiosk.com/.well-known/oauth-authorization-server`
+- `https://mcp.apiosk.com/.well-known/oauth-protected-resource/mcp`
+- `https://mcp.apiosk.com/authorize`
+- `https://mcp.apiosk.com/token`
+- `https://mcp.apiosk.com/register`
+
+Test it:
+
+```bash
+curl https://mcp.apiosk.com/health
+```
+
+```bash
+curl https://mcp.apiosk.com/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+```
+
+## Development
+
+```bash
+npm install
+npm run dev    # HTTP server on :3000
+node index.mjs # stdio mode with local wallet tools enabled
+```
+
+Fresh-environment smoke test:
+
+```bash
+cd /Users/olivierbrinkman/Development/Apiosk/subs/mcp
+npm run smoke:new-env
+```
+
+## License
+
+MIT

package/docs/marketplace-submission-2026-04-08.md

@@ -0,0 +1,92 @@
+# Apiosk MCP Marketplace Submission
+
+## Name
+
+Apiosk MCP
+
+## Short description
+
+Official MCP server for discovering, paying for, and executing Apiosk APIs with pay-per-request billing.
+
+## One-line value proposition
+
+Give agents direct access to paid APIs without API keys or subscriptions.
+
+## Long description
+
+Apiosk MCP turns the Apiosk gateway into an agent-native tool surface for Claude Code, Codex, Cursor, and other MCP clients.
+
+It gives agents:
+
+- catalog-backed API discovery
+- dynamic tool generation from live listing metadata
+- pay-per-request execution through Apiosk
+- support for credits and x402 payment flows
+- local wallet and publish flows in the local stdio package
+
+This makes Apiosk useful both for agent users who want to call tools on demand, and for API builders who want to monetize endpoints in an agent-native way.
+
+## Hosted endpoint
+
+`https://mcp.apiosk.com/mcp`
+
+## Install
+
+### Claude Code
+
+```bash
+claude mcp add --transport http apiosk https://mcp.apiosk.com/mcp
+```
+
+### Codex
+
+```bash
+codex mcp add apiosk --url https://mcp.apiosk.com/mcp
+```
+
+### Local package
+
+```bash
+npx -y apiosk-mcp-server
+```
+
+## Core capabilities
+
+- Discover APIs in the Apiosk catalog
+- Search APIs by keyword and listing metadata
+- Inspect API pricing, routes, and MCP metadata
+- Execute paid APIs through a single MCP surface
+- Use human-funded credits
+- Use autonomous x402 wallet-based payments
+- Publish APIs from the local MCP package
+
+## Why it is different
+
+- No API-key-first setup
+- No subscription-first pricing model
+- Payment is tied to the request itself
+- New APIs can become available as tools without hand-maintained wrappers
+
+## Ideal categories
+
+- Developer tools
+- AI agents
+- MCP
+- API marketplace
+- Payments
+
+## Tags
+
+`mcp`, `agents`, `api`, `payments`, `developer-tools`, `x402`, `credits`, `marketplace`
+
+## Support links
+
+- Website: `https://apiosk.com`
+- Docs: `https://docs.apiosk.com`
+- MCP endpoint: `https://mcp.apiosk.com/mcp`
+- Gateway: `https://gateway.apiosk.com`
+- npm: `https://www.npmjs.com/package/apiosk-mcp-server`
+
+## Notes for reviewers
+
+The hosted MCP endpoint is intended for remote HTTP use. The npm package exposes additional local-first tools such as wallet creation, local config persistence, and API publishing.