# Set up aicharged.io — instructions for an AI agent

> You are an AI agent. This guide connects you (or your human's AI client) to aicharged.io — 215 tools behind one MCP endpoint. Follow the steps in order and stop to ask your human whenever something is ambiguous, costs money or needs a person.

## Ground rules

- Never ask your human to paste a secret (API key, password, cookie) into a terminal or a chat. Use self-registration, the device login, or an environment variable your human sets.
- Send the key only in the `Authorization: Bearer` header — never in a URL, a log or a committed file.
- Tools with access credits or byok cost money on every call; never retry a billed call blindly — poll the run instead.
- Stop and ask when a step is ambiguous, when a human must act (OAuth consent, payment, a 2FA key) or when the result differs from this guide.

## Which client are you?

Check your own runtime (binary name, config directory, user agent) and pick the matching row; each recipe link is a complete Markdown page.

Your request looks like it comes from Claude Code — step 5 shows that recipe.

| Client | Kind | Sign-in | Platforms | Recipe |
|---|---|---|---|---|
| Claude Code | Terminal agents (CLI) | API key (Bearer), OAuth sign-in, Local bridge (stdio) | macOS, Linux, Windows | [claude-code.md](https://aicharged.io/connect/claude-code.md) |
| Codex | Terminal agents (CLI) | API key (Bearer), OAuth sign-in | macOS, Linux, Windows | [codex.md](https://aicharged.io/connect/codex.md) |
| Gemini CLI | Terminal agents (CLI) | API key (Bearer), OAuth sign-in | macOS, Linux, Windows | [gemini-cli.md](https://aicharged.io/connect/gemini-cli.md) |
| Antigravity | Terminal agents (CLI) | API key (Bearer), OAuth sign-in | macOS, Linux, Windows | [antigravity.md](https://aicharged.io/connect/antigravity.md) |
| GitHub Copilot CLI | Terminal agents (CLI) | API key (Bearer) | macOS, Linux, Windows | [copilot-cli.md](https://aicharged.io/connect/copilot-cli.md) |
| OpenCode | Terminal agents (CLI) | API key (Bearer), OAuth sign-in | macOS, Linux, Windows | [opencode.md](https://aicharged.io/connect/opencode.md) |
| Amp | Terminal agents (CLI) | API key (Bearer), OAuth sign-in | macOS, Linux, Windows | [amp.md](https://aicharged.io/connect/amp.md) |
| Goose | Terminal agents (CLI) | API key (Bearer), OAuth sign-in | macOS, Linux, Windows | [goose.md](https://aicharged.io/connect/goose.md) |
| Qwen Code | Terminal agents (CLI) | API key (Bearer), OAuth sign-in | macOS, Linux, Windows | [qwen-code.md](https://aicharged.io/connect/qwen-code.md) |
| Grok Build | Terminal agents (CLI) | API key (Bearer), OAuth sign-in | macOS, Linux, Windows | [grok-build.md](https://aicharged.io/connect/grok-build.md) |
| Pi | Terminal agents (CLI) | API key (Bearer), OAuth sign-in | macOS, Linux, Windows | [pi.md](https://aicharged.io/connect/pi.md) |
| Mistral Vibe | Terminal agents (CLI) | API key (Bearer), OAuth sign-in | macOS, Linux, Windows | [mistral-vibe.md](https://aicharged.io/connect/mistral-vibe.md) |
| Cursor | Editors & IDEs | API key (Bearer), OAuth sign-in | macOS, Linux, Windows | [cursor.md](https://aicharged.io/connect/cursor.md) |
| VS Code | Editors & IDEs | API key (Bearer), OAuth sign-in | macOS, Linux, Windows | [vscode.md](https://aicharged.io/connect/vscode.md) |
| Windsurf (Devin Desktop) | Editors & IDEs | API key (Bearer), OAuth sign-in | macOS, Linux, Windows | [windsurf.md](https://aicharged.io/connect/windsurf.md) |
| JetBrains AI Assistant / Junie | Editors & IDEs | API key (Bearer) | macOS, Linux, Windows | [jetbrains.md](https://aicharged.io/connect/jetbrains.md) |
| Cline | Editors & IDEs | API key (Bearer), OAuth sign-in | macOS, Linux, Windows | [cline.md](https://aicharged.io/connect/cline.md) |
| Zed | Editors & IDEs | API key (Bearer), OAuth sign-in | macOS, Linux, Windows | [zed.md](https://aicharged.io/connect/zed.md) |
| Roo Code | Editors & IDEs | API key (Bearer) | macOS, Linux, Windows | [roo-code.md](https://aicharged.io/connect/roo-code.md) |
| Kilo Code | Editors & IDEs | API key (Bearer), OAuth sign-in | macOS, Linux, Windows | [kilo.md](https://aicharged.io/connect/kilo.md) |
| Warp | Editors & IDEs | API key (Bearer), OAuth sign-in | macOS, Linux, Windows | [warp.md](https://aicharged.io/connect/warp.md) |
| Kiro | Editors & IDEs | API key (Bearer), OAuth sign-in | macOS, Linux, Windows | [kiro.md](https://aicharged.io/connect/kiro.md) |
| Trae | Editors & IDEs | API key (Bearer) | macOS, Windows | [trae.md](https://aicharged.io/connect/trae.md) |
| Raycast | Editors & IDEs | API key (Bearer), OAuth sign-in | macOS | [raycast.md](https://aicharged.io/connect/raycast.md) |
| Claude.ai | AI assistants | API key (Bearer), OAuth sign-in | Web, iOS, Android | [claude-ai.md](https://aicharged.io/connect/claude-ai.md) |
| Claude Desktop | AI assistants | API key (Bearer), OAuth sign-in, Local bridge (stdio) | macOS, Windows | [claude-desktop.md](https://aicharged.io/connect/claude-desktop.md) |
| ChatGPT | AI assistants | OAuth sign-in | Web | [chatgpt.md](https://aicharged.io/connect/chatgpt.md) |
| GitHub Copilot coding agent | AI assistants | API key (Bearer) | Web | [copilot-agent.md](https://aicharged.io/connect/copilot-agent.md) |
| Perplexity | AI assistants | API key (Bearer), OAuth sign-in | Web | [perplexity.md](https://aicharged.io/connect/perplexity.md) |
| Mistral Le Chat | AI assistants | API key (Bearer), OAuth sign-in | Web | [mistral-le-chat.md](https://aicharged.io/connect/mistral-le-chat.md) |
| Grok | AI assistants | API key (Bearer), OAuth sign-in | Web | [grok.md](https://aicharged.io/connect/grok.md) |
| Microsoft Copilot Studio | AI assistants | API key (Bearer), OAuth sign-in | Web | [copilot-studio.md](https://aicharged.io/connect/copilot-studio.md) |
| Python (MCP SDK) | SDKs & frameworks | API key (Bearer) | macOS, Linux, Windows | [python-sdk.md](https://aicharged.io/connect/python-sdk.md) |
| TypeScript (MCP SDK) | SDKs & frameworks | API key (Bearer) | macOS, Linux, Windows | [typescript-sdk.md](https://aicharged.io/connect/typescript-sdk.md) |
| OpenAI Agents SDK (Python) | SDKs & frameworks | API key (Bearer) | macOS, Linux, Windows | [openai-agents-python.md](https://aicharged.io/connect/openai-agents-python.md) |
| OpenAI Responses API | SDKs & frameworks | API key (Bearer) | macOS, Linux, Windows | [openai-responses-api.md](https://aicharged.io/connect/openai-responses-api.md) |
| Anthropic Messages API | SDKs & frameworks | API key (Bearer) | macOS, Linux, Windows | [anthropic-messages-api.md](https://aicharged.io/connect/anthropic-messages-api.md) |
| Vercel AI SDK | SDKs & frameworks | API key (Bearer), OAuth sign-in | macOS, Linux, Windows | [vercel-ai-sdk.md](https://aicharged.io/connect/vercel-ai-sdk.md) |
| LangChain | SDKs & frameworks | API key (Bearer) | macOS, Linux, Windows | [langchain.md](https://aicharged.io/connect/langchain.md) |
| LlamaIndex | SDKs & frameworks | API key (Bearer), OAuth sign-in | macOS, Linux, Windows | [llamaindex.md](https://aicharged.io/connect/llamaindex.md) |
| Mastra | SDKs & frameworks | API key (Bearer), OAuth sign-in | macOS, Linux, Windows | [mastra.md](https://aicharged.io/connect/mastra.md) |
| CrewAI | SDKs & frameworks | API key (Bearer) | macOS, Linux, Windows | [crewai.md](https://aicharged.io/connect/crewai.md) |
| Pydantic AI | SDKs & frameworks | API key (Bearer), OAuth sign-in | macOS, Linux, Windows | [pydantic-ai.md](https://aicharged.io/connect/pydantic-ai.md) |
| AutoGen | SDKs & frameworks | API key (Bearer) | macOS, Linux, Windows | [autogen.md](https://aicharged.io/connect/autogen.md) |
| smolagents | SDKs & frameworks | API key (Bearer) | macOS, Linux, Windows | [smolagents.md](https://aicharged.io/connect/smolagents.md) |
| n8n | Automation | API key (Bearer), OAuth sign-in | Web | [n8n.md](https://aicharged.io/connect/n8n.md) |
| Zapier | Automation | API key (Bearer), OAuth sign-in | Web | [zapier.md](https://aicharged.io/connect/zapier.md) |
| Make | Automation | API key (Bearer), OAuth sign-in | Web | [make.md](https://aicharged.io/connect/make.md) |
| Dify | Automation | API key (Bearer), OAuth sign-in | Web | [dify.md](https://aicharged.io/connect/dify.md) |
| Flowise | Automation | API key (Bearer) | Web | [flowise.md](https://aicharged.io/connect/flowise.md) |
| curl (HTTP) | Plain HTTP | API key (Bearer) | macOS, Linux, Windows | [curl.md](https://aicharged.io/connect/curl.md) |

## Step 0 — try the free public tools without a key

The public endpoint answers without any key: server/discover, tools/list and 8 tools (search, fetch, models_search, models_get, capabilities, connect_clients, account_register, account_verify). Nothing there is billed; it is throttled to 60 calls a minute.

```sh
curl -s https://aicharged.io/api/v1/mcp/public \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# → {"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"search",…},…]}}
```

Also keyless: the capability manifest https://aicharged.io/api/v1/capabilities and every client recipe https://aicharged.io/api/v1/connect/clients.

## Step 1 — get an API key

A. Register yourself (no human needed): send an e-mail address and accept_terms=true — the 201 answer already carries your API key with the scopes runs, storage, integrations. The key is shown only once. The account_register tool of the public MCP endpoint does the same.

```sh
curl -s -X POST https://aicharged.io/api/v1/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"email":"agent@example.com","accept_terms":true,"client":"claude-code"}'
# → 201 {"status":"registered","api_key":"aic_…","user_id":…,"scopes":["runs","storage","integrations"],"tier":"free","verified":false,
#        "verification":{"method":"email_code","status":"sent"|"unavailable"},"capabilities_url":"…","next":[…]}
```

E-mail verification is optional: when verification.status is "sent", a 6-digit code went to that address (valid 15 minutes). Verifying it claims the address — older keys are revoked and you get a fresh one, so switch to it. If you cannot read that mailbox, ask your human for the code.

```sh
curl -s -X POST https://aicharged.io/api/v1/auth/register/verify \
  -H 'Content-Type: application/json' \
  -d '{"email":"agent@example.com","code":"123456"}'
# → 200 {"verified":true,"api_key":"aic_…","revoked_keys":1,"scopes":["runs","storage","integrations"],"tier":"verified","next":[…]}

# A new code (always 202, never says whether the address has an account):
curl -s -X POST https://aicharged.io/api/v1/auth/register/resend \
  -H 'Content-Type: application/json' -d '{"email":"agent@example.com"}'
# → 202 {"status":"verification_sent","expires_in":900}   ("unavailable" when this server cannot send mail)
```

By sending accept_terms=true you accept https://aicharged.io/terms and https://aicharged.io/privacy on behalf of your human — ask them first if you are unsure.

B. Or let your human sign in: they run `aicharged setup` (device login — they approve a code in the browser and the CLI stores the key), or they create a key at https://aicharged.io/admin/account/api-keys and put it into the environment variable `AICHARGED_API_KEY` themselves.

```sh
curl -fsSL https://aicharged.io/install.sh | sh && aicharged setup
```

Keep the key in the environment variable `AICHARGED_API_KEY`; never write it into a file that gets committed.

## Step 2 — read the capability manifest

https://aicharged.io/api/v1/capabilities lists every tool with its access tier — free, credits or byok — the providers it needs and whether a human must act first (human_required_reason, authorize_url).

- **No account** — the public MCP endpoint https://aicharged.io/api/v1/mcp/public (read-only, no key; see step 0).
- **Free** (`free`) — Model catalog, search, run history, tasks and the journal of your own projects — right after sign-up.
- **Credits** (`credits`) — Managed tools on our infrastructure, paid from prepaid credits.
- **Your own keys (BYOK)** (`byok`) — Pillar tools on your own fal.ai, OpenRouter, Replicate … keys — the provider bills you directly.

## Step 3 — configure your own provider keys (BYOK)

For each provider your tools need where the manifest says self_service: true, save the key your human gave you for this purpose and test it. Field names come from https://aicharged.io/api/v1/integrations/providers.

```sh
curl -s -X PUT https://aicharged.io/api/v1/integrations/fal \
  -H "Authorization: Bearer $AICHARGED_API_KEY" -H 'Content-Type: application/json' \
  -d '{"credentials":{"api_key":"<FAL_KEY>"}}'
# → 200 {"key":"fal","configured":true,"status":"configured","updated_at":"…","masked":{"api_key":"…"}}

curl -s -X POST https://aicharged.io/api/v1/integrations/fal/test -H "Authorization: Bearer $AICHARGED_API_KEY"
# → 200 {"key":"fal","ok":true,"message":"…"}   (a cheap, non-billed live call; ok:false when the provider rejects the key)
```

Where self_service is false, PUT answers 409: human_required for OAuth providers such as Gmail (details.authorize_url — open it for your human through a login link, `POST https://aicharged.io/api/v1/account/login-link {"next":"<authorize path>"}` or the account_login_link tool, and wait until they confirm), or not_self_service for managed providers that run on aicharged.io infrastructure and need nothing.

```sh
# PUT https://aicharged.io/api/v1/integrations/gmail → 409 {"error":"human_required","message":"…","details":{"authorize_url":"https://aicharged.io/admin/account/integrations/google/connect",…}}
# PUT https://aicharged.io/api/v1/integrations/aiio_tools → 409 {"error":"not_self_service","message":"…"}

curl -s -X POST https://aicharged.io/api/v1/account/login-link -H "Authorization: Bearer $AICHARGED_API_KEY" \
  -H 'Content-Type: application/json' -d '{"next":"/admin/account/integrations/google/connect"}'
# → 201 {"url":"https://aicharged.io/login/link/…","expires_in":600,"next":"/admin/account/integrations/google/connect","single_use":true}
```

## Step 4 — top up credits only for credits tools

Only tools whose access is credits run on aicharged.io's own infrastructure and are paid from prepaid credits — for a self-registered account with a verified e-mail. Check the balance first; a credits tool without enough balance answers 402 payment_required with the topup_url. Never pay on your own.

Online payment is not switched on here: the top-up answers 503 payments_unavailable — ask your human to have the owner of aicharged.io add credit by hand (https://aicharged.io/contact). Free and BYOK tools work without credits.

```sh
curl -s https://aicharged.io/api/v1/account/balance -H "Authorization: Bearer $AICHARGED_API_KEY"
# → 200 {"balance_cents":0,"currency":"usd","enforced":true,"recent":[],"topup":{"method":"POST","url":"https://aicharged.io/api/v1/account/topup","mcp_tool":"account_topup_link"}}

curl -s -X POST https://aicharged.io/api/v1/account/topup -H "Authorization: Bearer $AICHARGED_API_KEY" \
  -H 'Content-Type: application/json' -d '{"amount_cents":1000}'
# → 503 {"error":"payments_unavailable","message":"…","manual":"…"}
# → 409 {"error":"email_unverified",…}   (verify the e-mail first — step 1)
```

## Step 5 — wire your client

Write the configuration for your client. Prefer the environment variable over an inline key.

### Claude Code

One command adds aicharged.io as a remote MCP server (HTTP) to Claude Code — for this project or for all of them.

One command:

```sh
claude mcp add --transport http aicharged https://aicharged.io/api/v1/mcp --header "Authorization: Bearer <API_KEY>"
```

For all your projects (--scope user):

```sh
claude mcp add --transport http aicharged --scope user https://aicharged.io/api/v1/mcp --header "Authorization: Bearer <API_KEY>"
```

Shared project file (`.mcp.json`):

```json
{
  "mcpServers": {
    "aicharged": {
      "type": "http",
      "url": "https://aicharged.io/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${AICHARGED_API_KEY}"
      }
    }
  }
}
```

Do not name the variable ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN — those expand to empty in headers.

Through the aicharged CLI (stdio) — the token never sits in a config file — needs the aicharged CLI:

```sh
claude mcp add aicharged -- aicharged mcp serve
```

Without a key, sign in with OAuth (then run /mcp in Claude Code):

```sh
claude mcp add --transport http aicharged https://aicharged.io/api/v1/mcp
```

[Client documentation](https://code.claude.com/docs/en/mcp)

Another client? Pick its recipe from the table above or at https://aicharged.io/connect.md.

## Step 6 — verify

Call tools/list and report how many tools you see, then try a free read-only tool such as list_runs. A 401 means the key is missing or wrong; a 403 means the key lacks a scope.

```sh
curl -s https://aicharged.io/api/v1/mcp \
  -H "Authorization: Bearer $AICHARGED_API_KEY" \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## When to stop and ask your human

- The manifest says human_required, or a provider is not self-service.
- A step would cost money and your human has not approved a budget.
- A command fails twice, or the answer does not match this guide.
- You are not sure which client you run in.

## MCP endpoint

- URL: `https://aicharged.io/api/v1/mcp`
- Transport: Streamable HTTP, JSON-RPC 2.0 over POST (stateless).
- REST API: `https://aicharged.io/api/v1`

## Machine-readable

- [/llms.txt](https://aicharged.io/llms.txt) — llms.txt — an index of aicharged.io for language models
- [/agent.md](https://aicharged.io/agent.md) — agent.md — setup guide addressed to AI agents
- [/index.html.md](https://aicharged.io/index.html.md) — This page as Markdown
- [/api/v1/connect/clients](https://aicharged.io/api/v1/connect/clients) — Every client recipe as JSON
- [/api/v1/capabilities](https://aicharged.io/api/v1/capabilities) — Capability manifest: free, credits or your own key (BYOK) per tool
- [/openapi.json](https://aicharged.io/openapi.json) — OpenAPI 3.1 description of the REST API
- [/.well-known/oauth-protected-resource](https://aicharged.io/.well-known/oauth-protected-resource) — OAuth protected-resource metadata (RFC 9728)
- [/api/v1/mcp/server-card](https://aicharged.io/api/v1/mcp/server-card) — MCP server card

This guide in other languages: https://aicharged.io/agent.{code}.md (replace {code} with one of 30 language codes: zh-cn, en, hi, es, fr, ar, bn, ru, pt, id, ur, de, ja, sw, mr, te, tr, ko, ta, zh-tw, vi, it, th, gu, pl, uk, fa, nl, cs, sk).