apiosk-mcp

<!-- 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, settled per call in USDC over x402, 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

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.2`; 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.2*
```

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"]
    }
  }
}
```

### 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
{
  "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, and managed agent-wallet CRUD. Public tools (discovery + guidance)
work before authorization; paid execution and managed tools require OAuth.

Publishing works on the hosted server too: `publish_x402_route` is listed in the
default tool surface, and authenticating with a provider key
(`Authorization: Bearer sk_live_...`) swaps in the full publisher toolkit. Only
the wallet-signed `apiosk_publish_api` 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.

## 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_