> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiosk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Clients

> Connect Apiosk to ChatGPT, Claude Code, Codex, and other MCP clients.

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

```text theme={null}
https://mcp.apiosk.com/mcp
```

Fallback if your apex proxy is deployed:

```text theme={null}
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.

<details>
  <summary>See a representative tool payload</summary>

  ```json theme={null}
  {
    "tool": "bella-pizza",
    "input": {
      "type": "Tonno",
      "size": "Small"
    },
    "response": {
      "api": "bella-pizza",
      "operation": "/orders",
      "status": "success",
      "payment_rail": "credits",
      "result": {
        "order_id": "94429859",
        "address": "Saved address on file"
      }
    }
  }
  ```
</details>

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

```bash theme={null}
claude mcp add apiosk -- npx -y apiosk-mcp-server
```

Check the saved server:

```bash theme={null}
claude mcp get apiosk
```

List configured MCP servers:

```bash theme={null}
claude mcp list
```

## Codex

Add Apiosk:

```bash theme={null}
codex mcp add apiosk -- npx -y apiosk-mcp-server
```

Check the saved server:

```bash theme={null}
codex mcp get apiosk
```

List configured MCP servers:

```bash theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

```bash theme={null}
claude mcp add --transport http apiosk https://mcp.apiosk.com/mcp
claude mcp get apiosk
```

### Codex

```bash theme={null}
codex mcp add apiosk --url https://mcp.apiosk.com/mcp
codex mcp get apiosk
```

## Paid API access

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`

## Related links

* Hosted MCP endpoint: [https://mcp.apiosk.com/mcp](https://mcp.apiosk.com/mcp)
* npm package: [https://www.npmjs.com/package/apiosk-mcp-server](https://www.npmjs.com/package/apiosk-mcp-server)
* Consumer guide: [/guides/consumers](/guides/consumers)