# OpenCode (https://upapi.io/docs/agent-setup/opencode)



**Onboard your AI agent to upAPI:** [Claude](https://claude.ai/directory/upapi), [ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_6ac97e64f7988191967fd96df23a0822), or add `https://app.upapi.io/api/mcp` (HTTP) to any other MCP client and sign in with your upAPI account.

Paste this into OpenCode and it connects itself:

```text
Connect upAPI to this agent.

1. Add {"type":"remote","url":"https://app.upapi.io/api/mcp"} as "upAPI" under "mcp" in opencode.json
2. Then run: opencode mcp auth upAPI A browser tab opens; sign in and click Allow access.
3. Call upAPI's search_tools and tell me what you can do.
```

Or do it by hand:

## OpenCode

### Hosted server (recommended)

Signs in through a browser with OAuth, so no key is written anywhere. Needs a full upAPI account: a guest session is refused with `401 GUEST_FORBIDDEN`.

1. Edit `~/.config/opencode/opencode.json`. Create the file if it is missing. Otherwise add the `upAPI` entry to the existing `mcp` object and keep everything else.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "upAPI": {
      "type": "remote",
      "url": "https://app.upapi.io/api/mcp",
      "enabled": true
    }
  }
}
```

2. Run:

```bash
opencode mcp auth upAPI
```

Opens a browser. The user finishes the upAPI sign-in there.

### Local server (fallback)

Use this only when the hosted server is not an option: a guest account, no browser on this machine, or the user asks for it. It runs `npx -y @upapi/mcp` on this machine and authenticates with `UPAPI_API_KEY`. The hosted server serves every public operation; the npm package catches up in its next release (the published 0.2.0 build serves the catalog without the account tools).

1. Edit `~/.config/opencode/opencode.json`. Merge into `mcp` as above. `{env:UPAPI_API_KEY}` is OpenCode's own substitution, so the key stays out of the file.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "upAPI": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@upapi/mcp"
      ],
      "enabled": true,
      "environment": {
        "UPAPI_API_KEY": "{env:UPAPI_API_KEY}",
        "UPAPI_TOOL_MODE": "compact"
      }
    }
  }
}
```

Check: `opencode mcp list` shows `upAPI`.

## Verify

Run `curl -sS https://api.upapi.io/usage -H "x-api-key: $UPAPI_API_KEY"`. Success is HTTP 200 and a JSON object with `plan`, `remainingMonth` and `units`. A 401 with the code `UNAUTHORIZED` means the key is wrong or was deleted: ask the user for a new one. A 403 `FORBIDDEN` naming the `usage:read` scope means the key is valid but was created as Execute only: it still calls operations, so keep it and tell the user this check could not read the quota. A 503 is an outage, not a bad key: wait and retry.

Then call the `search_ops` tool with `{"query": "github repository stats"}`. Success is a list of operations that includes the slug `github-repo.get`. If the upAPI tools are not visible yet, the server is waiting for the user to finish the browser sign-in.
