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



Paste this into OpenCode and it will set itself up:

```text
Fetch and execute the appropriate instructions to set me up for upAPI from https://upapi.io/docs/agent-setup/prompt.md
```

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`. It also serves the Social Media and Utility operations the hosted server withholds.

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.