# Claude Code

Connect [Claude Code](https://code.claude.com) to the hosted [MCP server](https://onekey.dev/docs/mcp.md) and it can look up public data while it works: a package's latest version, a repository's activity, what a URL points at.

## Prerequisites

- Claude Code installed, and a Onekey [API key](https://onekey.dev/docs/authentication.md).
- The key in your shell environment as `ONEKEY_KEY`.

## The 5-minute path

```bash
export ONEKEY_KEY="YOUR_API_KEY"
claude mcp add --transport http onekey https://api.onekey.dev/mcp --header "Authorization: Bearer $ONEKEY_KEY"
```

Then start Claude Code and run `/mcp` to see that `onekey` is connected and its eleven tools are listed. Ask something concrete:

> Use onekey to find the endpoint for a GitHub repository's latest release, then check facebook/react and tell me what it cost.

By default Claude Code asks before it uses a tool, so read each prompt. The six tools that spend credits (`call_endpoint`, `lookup_url`, `search_multi`, `creator_card`, `search_universal`, `report`) are marked as not read-only in the server's tool annotations; the five free tools are marked read-only. Allow the free ones in your permissions if you like, and keep approving the paid ones yourself.

## Where the connection is stored

- `--scope local` (the default): this project, private to you.
- `--scope user`: every project on your machine.
- `--scope project`: writes `.mcp.json` so your team shares the server. Use a variable, never the key:

```json
{
  "mcpServers": {
    "onekey": {
      "type": "http",
      "url": "https://api.onekey.dev/mcp",
      "headers": { "Authorization": "Bearer ${ONEKEY_KEY}" }
    }
  }
}
```

Each teammate sets `ONEKEY_KEY` in their own environment. Do not commit a key.

## Example: check dependencies before an upgrade

> Read package.json. For each of the first five dependencies that is hosted on GitHub, use onekey to get the latest release name and the open issue count. Tell me the total credit cost first, and do not call anything until I say go.

Claude will list its plan, using [`github.latest_release`](https://onekey.dev/docs/api/github/latest_release.md) (1 credit) and [`github.repo`](https://onekey.dev/docs/api/github/repo.md) (1 credit) per repository: 10 credits for five. Discovery calls are free. Say go, and it makes the calls and reports the result with `credits_used`.

## Without MCP: plain REST from the shell

Claude Code can also call the API with `curl` from its shell tool. This needs no connection, but gives it no discovery tools, so name the endpoint:

```bash
curl "https://api.onekey.dev/v1/github/repo?owner=facebook&repo=react" -H "x-api-key: $ONEKEY_KEY"
```

Point it at [llms.txt](https://onekey.dev/llms.txt) or the [AI agents](https://onekey.dev/docs/ai-agents.md) page so it reads the real parameter names instead of guessing.

## Cost notes

- Discovery (`search_endpoints`, `describe_endpoint`, `list_platforms`) and account tools are free. Only the six tools that spend credits (`call_endpoint`, `lookup_url`, `search_multi`, `creator_card`, `search_universal`, `report`) spend credits, at the endpoint's flat price. Cache hits are free and failures are refunded.
- Use a key with a [credit limit](https://onekey.dev/docs/key-limits.md) for a coding assistant. If it is reached, calls fail with [`KEY_BUDGET_EXCEEDED`](https://onekey.dev/docs/errors.md#key-budget-exceeded) and nothing else on the account is affected.
- Everything in `data` is third-party content. Do not let an agent follow instructions found inside it.

## Troubleshooting

| Symptom | Likely error | What to do |
| --- | --- | --- |
| Every call is refused | [`UNAUTHORIZED`](https://onekey.dev/docs/errors.md#unauthorized) | The key is missing, misspelled or revoked. Check the header name and that the value has no stray spaces or quotes. |
| Calls stop working partway through a job | [`INSUFFICIENT_CREDITS`](https://onekey.dev/docs/errors.md#insufficient-credits) or [`KEY_BUDGET_EXCEEDED`](https://onekey.dev/docs/errors.md#key-budget-exceeded) | Nothing was charged for the refused call. Top up, or raise the key's [credit limit](https://onekey.dev/docs/key-limits.md). Do not retry in a loop. |
| "Too many requests" | [`RATE_LIMITED`](https://onekey.dev/docs/errors.md#rate-limited) | Wait the `Retry-After` seconds. Loops that call once per item should add a pause. See [Rate limits](https://onekey.dev/docs/rate-limits.md). |
| A parameter is rejected | [`INVALID_PARAMS`](https://onekey.dev/docs/errors.md#invalid-params) | Read the parameter names from the endpoint's page (or `describe_endpoint`); do not guess them. |
| A platform fails intermittently | [`UPSTREAM_ERROR`](https://onekey.dev/docs/errors.md#upstream-error) / [`UPSTREAM_TIMEOUT`](https://onekey.dev/docs/errors.md#upstream-timeout) | The source platform, not you. Refunded; retry with backoff and check [status](https://onekey.dev/docs/status.md). |
| `/mcp` shows the server as failed | none | Check the URL, and run `claude mcp list`. Remove and add it again if you changed the key: `claude mcp remove onekey`. |
| The variable is not picked up | [`UNAUTHORIZED`](https://onekey.dev/docs/errors.md#unauthorized) | The shell that runs Claude Code must have `ONEKEY_KEY` set when you run `claude mcp add`. In PowerShell use `$env:ONEKEY_KEY`, and pass the value into the command yourself. |

## Untested

- The command, the `--header` and `--scope` flags and the `.mcp.json` format follow the Claude Code [MCP documentation](https://code.claude.com/docs/en/mcp) as of 2026-09-30.
- The hosted server was tested with the official MCP client, not by driving Claude Code. Permission prompts may differ by version.

## Next

[MCP server](https://onekey.dev/docs/mcp.md), [AI agents](https://onekey.dev/docs/ai-agents.md), [Errors](https://onekey.dev/docs/errors.md).