Skip to main content

​
MCP Clients

Apiosk supports both hosted remote MCP and local stdio MCP. Once connected, the client can use live Apiosk tools like apiosk_help, apiosk_search, apiosk_get_api, apiosk_execute, apiosk_get_started, and dynamic API-specific tools generated from the catalog.

​
GPT-native clients

If you are connecting Apiosk to ChatGPT or another remote MCP client, use the hosted endpoint: 
https://mcp.apiosk.com/mcp
Fallback if your apex proxy is deployed: 
https://apiosk.com/mcp

​
Quick setup

  1. Add https://mcp.apiosk.com/mcp as the remote MCP server in ChatGPT Developer Mode or another GPT-native MCP client.
  2. Complete the hosted OAuth sign-in with your Apiosk dashboard account.
  3. Refresh the connector or start a new chat if the client cached older tool definitions.

​
How the hosted GPT flow works

  • Public discovery can be visible before sign-in.
  • Protected tools challenge for OAuth and unlock after login.
  • You do not need to upload a handoff file to use the MCP connector.
  • The handoff file is only for manual gateway calls and non-MCP runtimes.

​
Billing behavior

  • Hosted GPT-native MCP clients authenticate as your dashboard session.
  • Direct gateway calls with X-Apiosk-Connect-Token or local wallet-backed x-payment proofs remain the path for raw agent-wallet and x402 execution.
  • If you need a specific rail, choose the runtime and auth mode deliberately instead of assuming all clients settle the same way.

​
Claude Code

Add Apiosk: 
claude mcp add apiosk -- npx -y apiosk-mcp-server
Check the saved server: 
claude mcp get apiosk
List configured MCP servers: 
claude mcp list

​
Codex

Add Apiosk: 
codex mcp add apiosk -- npx -y apiosk-mcp-server
Check the saved server: 
codex mcp get apiosk
List configured MCP servers: 
codex mcp list

​
What each command does

  • add registers the Apiosk MCP server in your local client config.
  • get shows the saved configuration for apiosk and whether the client can connect.
  • list shows configured MCP servers. It does not list internal Apiosk tools one by one.

​
First-run setup in local stdio mode

If you use the npm package locally, the fastest way to get from install to a working paid-capable setup is to call apiosk_get_started. Create a local wallet automatically, discover the catalog, and run a small test call: 
{
  "wallet_label": "My Apiosk wallet",
  "test_slug": "agent-json-diff",
  "test_input": {
    "before": { "ok": true },
    "after": { "ok": false }
  }
}
Or import a dashboard connect string and verify it immediately: 
{
  "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
}
apiosk_get_started is only available in local stdio mode because it saves local wallet or connect-token state under ~/.apiosk.

​
Hosted MCP alternative

If you prefer the hosted MCP endpoint instead of the npm package, use the public URL:

​
Claude Code

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

​
Codex

codex mcp add apiosk --url https://mcp.apiosk.com/mcp
codex mcp get apiosk
Installing the MCP server is public. Some paid Apiosk routes still require a valid payment or auth mode when a tool actually calls them. For the local npm package, apiosk_get_started is the recommended entrypoint because it can save a connect string locally or create a wallet and then prove the setup with a first execute call. Common environment variables:
  • APIOSK_PRIVATE_KEY
  • APIOSK_CONNECT_TOKEN
  • APIOSK_CONNECT_AUTHORIZATION
  • APIOSK_X_PAYMENT