Apiosk MCP Server

Buy an API call the way a person would. Describe the job, see what can do it, compare the candidates on price and measured performance, choose one, and pay for it in USDC over x402 — under limits the buyer set, enforced on every call.

payments · x402 · commerce · usdc · api-comparison

• Hosted endpoint: https://mcp.apiosk.com/mcp (streamable HTTP; the first data request starts OAuth when needed).
• Local stdio package: npx -y @apiosk/mcp or uvx apiosk-mcp.
• Buyer portal: buy.apiosk.com — sign in, fund a wallet, set the limits, approve a held purchase.

The eleven tools

Two paths, and the same rules on both. apiosk is the one-shot entrypoint for fast shopping: it returns the App's own top ranked runnable provider and approval card. An agent does not browse a menu: it reads descriptions and picks, so every tool here earns its place in one of the two flows.

One call, when a single API answers the question:

Several calls, when a lookup's result feeds the next call, or several facts are wanted about one subject:

The plan is compiled, deduplicated and priced by the gateway, never here: a lookup two branches both need is bought once, and a fact you already hold removes its lookup from the plan and from the price. The App and this server show the same plan_hash and the same amount for the same intent because exactly one of them computes it.

Anything a buyer needs that is not on this list is a link to app.apiosk.com, not a tool. This server holds no keys, prices nothing and moves no money.

The one rule

apiosk_compare and apiosk return offers. A person approves or denies the purchase. The quick card states the provider and exact price and supplies the two actions; do not add a second prose confirmation. Only Approve may pass the signed offer_token, exact max_price_usdc ceiling and entered inputs to apiosk_execute. Deny stops without spending.

A plan is the same rule at plan scale: one confirmation, for the whole plan, at the whole price. apiosk_plan asks it once and returns the answer in status; apiosk_execute_plan asks nothing and accepts nothing but the plan_token, so it cannot build a plan, change one, or re-open a decision that was already made.

How the user is asked

The choice and the approval are the same question in three renderings, built from one description of the offers, so a row is called the same thing wherever it appears:

Interactive UI in Claude's own chat surfaces is limited to connectors approved for the Connectors Directory, so the elicitation path is what a Claude user gets today and the cards are what ChatGPT and MCP-UI hosts get.

The three outcomes that are not failures

apiosk_execute can come back without a result, and none of these should be retried blindly:

apiosk_execute_plan adds one more, and it is not a failure either:

Quick start

npx -y @apiosk/mcp

The scoped npm package is canonical:

npm install @apiosk/mcp

It exposes the same CLI binaries:

npx -y @apiosk/mcp
apiosk-mcp
apiosk-mcp-server
apiosk

The PyPI package is a launcher for it, so uvx apiosk-mcp starts the same server as npx -y @apiosk/mcp.

The hosted server starts its OAuth handoff on the first /apiosk, discovery or comparison request, then resumes the request after the buyer approves the connection at buy.apiosk.com. For local stdio, set APIOSK_CONNECT_TOKEN or call apiosk_connect for the connection link.

Agent configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "apiosk": {
      "command": "npx",
      "args": ["-y", "@apiosk/mcp"]
    }
  }
}

VS Code

code --add-mcp '{"name":"apiosk","command":"npx","args":["-y","@apiosk/mcp"]}'

Or .vscode/mcp.json (VS Code uses a servers key):

{
  "servers": {
    "apiosk": {
      "command": "npx",
      "args": ["-y", "@apiosk/mcp"]
    }
  }
}

The hosted endpoint instead of the local package:

{
  "servers": {
    "apiosk": {
      "type": "http",
      "url": "https://mcp.apiosk.com/mcp"
    }
  }
}

Claude Code

claude mcp add --transport http apiosk https://mcp.apiosk.com/mcp

Cursor, Windsurf, Cline, Continue, Goose

{
  "mcpServers": {
    "apiosk": {
      "command": "npx",
      "args": ["-y", "@apiosk/mcp"]
    }
  }
}

A local checkout

{
  "mcpServers": {
    "apiosk": {
      "command": "node",
      "args": ["/full/path/to/apiosk-mcp/index.mjs"]
    }
  }
}

ChatGPT and other remote MCP apps

Use https://mcp.apiosk.com/mcp. The first tool that reads provider data starts OAuth automatically when the session is not connected; sign-in and spending limits live on the buyer portal. apiosk_connect remains available as the read-only diagnostic and reconnection entrypoint.

The OpenAI plugin package lives in plugin/apiosk. It combines this MCP server with the apiosk skill, so one installation provides both the live tools and the workflow instructions. The hosted server also exposes the bounded MCP skills extension used by OpenAI's Scan Tools action. A skill-only upload is available from the same source at plugin/apiosk/skills/apiosk.

Examples

Check the connection

{ "name": "apiosk_connect", "arguments": {} }

Unconnected, it returns the portal link and says plainly that nothing can be paid for yet. Connected, it names the wallet, the policy and the exact per-transaction and daily limits, so the agent can quote them to the user without a second round trip.

Find and compare

{ "name": "apiosk_discover", "arguments": { "query": "realtime USD to EUR exchange rate" } }