@apiosk/mcp 1.3.0 → 1.7.0

package/README.md

@@ -1,7 +1,25 @@
+<!-- mcp-name: io.github.obcraft/apiosk-mcp -->
+<p align="center">
+  <img src="https://apiosk.com/logo.svg" alt="Apiosk" width="120" />
+</p>
+
 # Apiosk MCP Server
 
+**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.
+
+`payments` · `finance` · `x402` · `commerce` · `crypto`
+
+[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.obcraft%2Fapiosk--mcp-2ea44f)](https://registry.modelcontextprotocol.io)
+[![npm](https://img.shields.io/npm/v/@apiosk/mcp?label=npm%20%40apiosk%2Fmcp)](https://www.npmjs.com/package/@apiosk/mcp)
+[![PyPI](https://img.shields.io/pypi/v/apiosk-mcp?label=PyPI%20apiosk-mcp)](https://pypi.org/project/apiosk-mcp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](#license)
+
 Official MCP server for discovering, paying for, and publishing Apiosk APIs.
 
+- **Listed in the [official MCP Registry](https://registry.modelcontextprotocol.io)** as `io.github.obcraft/apiosk-mcp`.
+- **Hosted endpoint:** `https://mcp.apiosk.com/mcp` (streamable HTTP, OAuth-protected for paid tools).
+- **Local stdio package:** `npx -y @apiosk/mcp` or `uvx apiosk-mcp` for wallet + publish tools.
+
 ## Quick Start
 
 ### Package names
@@ -46,7 +64,7 @@ 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
+`npx -y @apiosk/mcp@1.3.2`; set `APIOSK_MCP_NPM_PACKAGE=@apiosk/mcp@next` to
 override the npm package spec.
 
 ### Publishing packages
@@ -61,7 +79,7 @@ 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*
+python3 -m twine upload dist/apiosk_mcp-1.3.2*
 ```
 
 After both uploads are live, the MCP registry package fields are:
@@ -126,6 +144,40 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 }
 ```
 
+### VS Code
+
+Add the server with the CLI:
+
+```bash
+code --add-mcp '{"name":"apiosk","command":"npx","args":["-y","@apiosk/mcp"]}'
+```
+
+Or create `.vscode/mcp.json` in your workspace (VS Code uses a `servers` key):
+
+```json
+{
+  "servers": {
+    "apiosk": {
+      "command": "npx",
+      "args": ["-y", "@apiosk/mcp"]
+    }
+  }
+}
+```
+
+To use the hosted endpoint instead of the local package:
+
+```json
+{
+  "servers": {
+    "apiosk": {
+      "type": "http",
+      "url": "https://mcp.apiosk.com/mcp"
+    }
+  }
+}
+```
+
 ### Cursor
 
 ```json
@@ -208,7 +260,7 @@ 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
+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
@@ -254,20 +306,85 @@ 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.
 
+## Publish Paid x402 Routes from a Coding Agent
+
+The hosted MCP doubles as a **publisher** for coding agents (Claude Code,
+Cursor, Codex, and friends): build an API, then publish it as a paid x402
+endpoint on the Apiosk gateway in one tool call.
+
+Authenticate with an Apiosk **provider API key** (`sk_live_…`, minted in the
+provider portal under Settings → API keys):
+
+```json
+{
+  "mcpServers": {
+    "apiosk": {
+      "url": "https://mcp.apiosk.com/mcp",
+      "headers": {
+        "Authorization": "Bearer sk_live_YOUR_PROVIDER_KEY"
+      }
+    }
+  }
+}
+```
+
+Tools:
+
+- `publish_x402_route`: create a paid route: name, `upstream_url`, `price`
+  (USDC per call), `settlement_address`, optional `method`/`path`/schemas/tags.
+  Returns the `paid_url` on `gateway.apiosk.com` plus the route's status.
+- `list_x402_routes`: all your routes with paid URLs, prices, and status.
+- `update_x402_route`: change price, description, upstream URL, schemas,
+  settlement address, or status.
+- `unpublish_x402_route`: disable a route (reversible).
+- `test_x402_route`: fire an unpaid request at the paid URL and verify it
+  returns `402 Payment Required` with a valid x402 `accepts[]` offer.
+- `generate_openapi_spec`: host an OpenAPI 3.1 spec for the route at
+  `https://mcp.apiosk.com/openapi/<route_id>.json`.
+- `publish_project`: publish several routes of one project in a single call.
+
+Lifecycle: new routes land in Apiosk's operator review queue
+(`status: "pending_review"`). On approval they serve x402 payments, appear in
+`https://gateway.apiosk.com/.well-known/x402`, and are auto-indexed in the
+Coinbase x402 Bazaar. Settlement pays 98% of each call to your
+`settlement_address` (Apiosk keeps a 2% platform fee).
+
+Discovery endpoints for machines:
+
+- `https://mcp.apiosk.com/.well-known/apiosk-routes.json` (alias `/discovery`)
+ , machine-readable index of every paid route on the gateway.
+- `https://mcp.apiosk.com/openapi/<route_id>.json`: per-route OpenAPI spec.
+
+Local stdio use: set `APIOSK_PROVIDER_TOKEN=sk_live_…` instead of the header.
+Hosted server operators must configure `APIOSK_SUPABASE_SERVICE_ROLE_KEY` (the
+tools verify provider keys and write listings through the gateway database).
+
 ## Available Tools
 
 Static tools:
 
 - `apiosk_help`
-- `apiosk_payment_guide` — buyer + provider guide for paying through and publishing on the gateway
+- `apiosk_payment_guide`: buyer + provider guide for paying through and publishing on the gateway
 - `apiosk_explore`
 - `apiosk_search`
+- `apiosk_discover`
+- `apiosk_inspect_x402`
+- `apiosk_fetch_paid`
 - `apiosk_get_api`
 - `apiosk_execute`
 
+`apiosk_search` also returns matching x402 discovery sources in `sources`, even
+when the Apiosk API catalog has no listing with that name. Each source includes
+its direct REST/MCP endpoints and marks paid endpoints with
+`payment_required`, `price_usdc`, and `executable_via`. `apiosk_discover` can
+query the wired free sources directly; paid discovery sources such as x402scan
+and Apify are returned as `apiosk_inspect_x402` → `apiosk_fetch_paid` pointers
+and are never paid automatically.
+
 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`
+- 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`
+- External paid fetch: `apiosk_fetch_paid` (OAuth/connect-token protected; requires explicit live-price confirmation)
 - 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`
 
@@ -290,6 +407,16 @@ Publish tools in stdio mode:
 - `apiosk_update_api`
 - `apiosk_delete_api`
 
+x402 publisher tools (all modes, provider-token auth):
+
+- `publish_x402_route`
+- `list_x402_routes`
+- `update_x402_route`
+- `unpublish_x402_route`
+- `test_x402_route`
+- `generate_openapi_spec`
+- `publish_project`
+
 Optional dashboard-managed wallet tools:
 
 - `apiosk_list_wallets`
@@ -326,7 +453,7 @@ Dynamic tools:
 ```
 
 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
+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.
 
@@ -344,7 +471,7 @@ what to do next.
 { "role": "buyer", "slug": "weather-now" }
 ```
 
-Returns a buyer guide (USDC/x402 or credits — tailored to the configured auth)
+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.
 
@@ -393,7 +520,7 @@ Or save a dashboard-managed connect string locally and verify it:
 
 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
+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.
 

package/docs/sepa-rail.md

@@ -1,7 +1,7 @@
-# Settlement rails — USDC, SEPA incasso, credits
+# Settlement rails: USDC, SEPA incasso, credits
 
 Apiosk is **one mandate, any rail**. A single buyer connect token can settle a
-paid API call over any of three rails. The gateway picks the rail per call —
+paid API call over any of three rails. The gateway picks the rail per call -
 the agent does not need to know or choose which one is used.
 
 | Rail | What it is | Best for |
@@ -12,8 +12,8 @@ the agent does not need to know or choose which one is used.
 
 ### Rail fallback order
 
-1. **USDC / x402 wallet** — when the agent can produce a payment proof.
-2. **SEPA incasso ledger** — when the buyer has an active SEPA mandate. No proof
+1. **USDC / x402 wallet**: when the agent can produce a payment proof.
+2. **SEPA incasso ledger**: when the buyer has an active SEPA mandate. No proof
    needed: the call is *recorded*, not blocked.
 3. **Prepaid credits** balance.
 
@@ -28,7 +28,7 @@ An incasso lets Apiosk pull euros from the buyer's bank account under a one-time
 mandate, so an agent can keep calling paid APIs without signing or funding each
 call.
 
-### 1. Mandate setup — once, by a human
+### 1. Mandate setup: once, by a human
 
 In the buyer portal the buyer authorizes a recurring SEPA mandate:
 
@@ -37,9 +37,9 @@ In the buyer portal the buyer authorizes a recurring SEPA mandate:
 - **PayPal** / **card**: alternative mandates for non-NL buyers (recurring calls
   use `method=paypal` / `method=creditcard`).
 
-Agents never perform this step — they only need the connect token afterward.
+Agents never perform this step, they only need the connect token afterward.
 
-### 2. Collection terms — once, by the buyer
+### 2. Collection terms: once, by the buyer
 
 The mandate authorizes bounded collection:
 
@@ -49,7 +49,7 @@ The mandate authorizes bounded collection:
 These bound how much, and for how long, calls can accrue before a collection is
 triggered.
 
-### 3. Per call — automatic, deferred
+### 3. Per call: automatic, deferred
 
 When a paid call settles over SEPA, the gateway appends a **SEPA ledger debit**
 row carrying the full breakdown and returns success immediately:
@@ -64,9 +64,9 @@ row carrying the full breakdown and returns success immediately:
 }
 ```
 
-No bank transaction happens yet — only a ledger entry.
+No bank transaction happens yet, only a ledger entry.
 
-### 4. Batch collection — background worker
+### 4. Batch collection: background worker
 
 A worker flushes a buyer's unbatched ledger into **one** Mollie SEPA Direct
 Debit when either condition is met:
@@ -83,7 +83,7 @@ edge function to create the direct debit.
 ## Economics
 
 - **Apiosk platform fee: 2% by default** of each call's gross, recorded per ledger row.
-- **Mollie SEPA Direct Debit fee: ~€0.30 per collection (per batch)** — not per
+- **Mollie SEPA Direct Debit fee: ~€0.30 per collection (per batch)**, not per
   call. This is why sub-€25 thresholds are not offered: batching amortizes the
   fixed bank fee across many calls.
 - The provider receives gross minus the Apiosk platform fee; the Mollie fee is netted
@@ -118,13 +118,13 @@ export APIO_WALLET_PER_TX_LIMIT_USDC=1
 The `APIO_WALLET_*` limits only bound the **USDC** rail. The **SEPA mandate and
 its threshold/age terms live server-side** against the same buyer account, so the
 identical connect token transparently settles over SEPA incasso when USDC is
-unavailable — no extra connect-string fields are required. An agent holding only
+unavailable, no extra connect-string fields are required. An agent holding only
 this connect token can therefore make paid calls with no on-chain balance; those
 calls land on the SEPA ledger and are collected in the next batch.
 
 ## Agent guidance
 
-- Agents do **not** set up the mandate — that is a one-time human action in the
+- Agents do **not** set up the mandate: that is a one-time human action in the
   buyer portal.
 - SEPA-backed calls succeed immediately even with no wallet balance and no x402
   proof; settlement is deferred to the batch.

package/dxt.json

@@ -1,10 +1,13 @@
 {
   "name": "apiosk-mcp",
-  "version": "1.3.0",
-  "description": "Official MCP server for browsing, paying for, and publishing Apiosk APIs",
+  "version": "1.7.0",
+  "description": "Discover, pay for, execute, and publish APIs through Apiosk.",
   "author": "Apiosk",
   "license": "MIT",
-  "repository": "https://github.com/apiosk/apiosk-mcp",
+  "homepage": "https://apiosk.com",
+  "icon": "https://mcp.apiosk.com/logo-optimized-light.png",
+  "keywords": ["payments", "finance", "x402", "commerce", "crypto"],
+  "repository": "https://github.com/obcraft/apiosk-mcp",
   "mcp": {
     "command": "node",
     "args": ["index.mjs"]
@@ -20,7 +23,7 @@
     },
     {
       "name": "apiosk_payment_guide",
-      "description": "Guide for paying through the Apiosk gateway — buyer (how to settle a paid call) and provider (how to publish and get paid)."
+      "description": "Guide for paying through the Apiosk gateway, buyer (how to settle a paid call) and provider (how to publish and get paid)."
     },
     {
       "name": "apiosk_get_api",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@apiosk/mcp",
-  "version": "1.3.0",
-  "description": "Official MCP server for browsing, paying for, and publishing Apiosk APIs",
+  "version": "1.7.0",
+  "description": "Discover, pay for, execute, and publish APIs through Apiosk.",
   "mcpName": "io.github.obcraft/apiosk-mcp",
   "main": "index.mjs",
   "exports": {
@@ -28,9 +28,12 @@
     "apiosk",
     "api",
     "model-context-protocol",
-    "x402",
     "agent-tools",
-    "payments"
+    "payments",
+    "finance",
+    "x402",
+    "commerce",
+    "crypto"
   ],
   "author": "Apiosk",
   "license": "MIT",
@@ -41,16 +44,17 @@
   "homepage": "https://apiosk.com",
   "repository": {
     "type": "git",
-    "url": "https://github.com/apiosk/mcp.git"
+    "url": "https://github.com/obcraft/apiosk-mcp.git"
   },
   "bugs": {
-    "url": "https://github.com/apiosk/mcp/issues"
+    "url": "https://github.com/obcraft/apiosk-mcp/issues"
   },
   "publishConfig": {
     "access": "public"
   },
   "files": [
     "index.mjs",
+    "logo-optimized-light.png",
     "server.mjs",
     "well-known.mjs",
     "server.json",
@@ -64,13 +68,14 @@
     "@modelcontextprotocol/sdk": "^1.27.1",
     "express": "^5.2.1",
     "qrcode": "^1.5.4",
-    "viem": "^2.47.0",
-    "zod": "^4.3.6"
+    "viem": "^2.47.0"
   },
   "devDependencies": {
     "@flydotio/dockerfile": "^0.7.10",
     "@types/express": "^5.0.6",
     "@types/node": "^25.5.0",
+    "@walletconnect/ethereum-provider": "^2.23.9",
+    "esbuild": "^0.28.1",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3"
   }

package/server.json

@@ -1,17 +1,91 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.obcraft/apiosk-mcp",
-  "title": "Apiosk",
-  "description": "Discover, pay for, execute, and publish Apiosk APIs through MCP.",
-  "version": "1.3.0",
+  "title": "Apiosk Connect",
+  "description": "Discover, pay for, execute, and publish APIs through Apiosk.",
+  "version": "1.7.0",
+  "websiteUrl": "https://apiosk.com",
+  "icons": [
+    {
+      "src": "https://mcp.apiosk.com/logo-optimized-light.png",
+      "mimeType": "image/png",
+      "sizes": ["2048x2048"]
+    },
+    {
+      "src": "https://apiosk.com/logo.svg",
+      "mimeType": "image/svg+xml",
+      "sizes": ["any"]
+    },
+    {
+      "src": "https://apiosk.com/apple-touch-icon.png",
+      "mimeType": "image/png",
+      "sizes": ["180x180"]
+    }
+  ],
   "repository": {
     "url": "https://github.com/obcraft/apiosk-mcp",
     "source": "github"
   },
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@apiosk/mcp",
+      "version": "1.7.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "APIOSK_PRIVATE_KEY",
+          "description": "Optional wallet private key for automatic x402 payments.",
+          "isRequired": false,
+          "isSecret": true,
+          "format": "string"
+        },
+        {
+          "name": "APIOSK_CONNECT_TOKEN",
+          "description": "Optional dashboard-managed access token.",
+          "isRequired": false,
+          "isSecret": true,
+          "format": "string"
+        }
+      ]
+    },
+    {
+      "registryType": "pypi",
+      "identifier": "apiosk-mcp",
+      "version": "1.7.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "APIOSK_PRIVATE_KEY",
+          "description": "Optional wallet private key for automatic x402 payments.",
+          "isRequired": false,
+          "isSecret": true,
+          "format": "string"
+        },
+        {
+          "name": "APIOSK_CONNECT_TOKEN",
+          "description": "Optional dashboard-managed access token.",
+          "isRequired": false,
+          "isSecret": true,
+          "format": "string"
+        }
+      ]
+    }
+  ],
   "remotes": [
     {
       "type": "streamable-http",
       "url": "https://mcp.apiosk.com/mcp"
     }
-  ]
+  ],
+  "_meta": {
+    "com.apiosk": {
+      "tags": ["payments", "finance", "x402", "commerce", "crypto"],
+      "categories": ["payments", "finance"]
+    }
+  }
 }