# Codex (https://upapi.io/docs/agent-setup/codex)



Paste this into Codex 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:

## Codex

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

```bash
codex mcp add upapi --url https://app.upapi.io/api/mcp
```

2. Run:

```bash
codex mcp login 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. Run:

```bash
codex mcp add upapi --env UPAPI_API_KEY="$UPAPI_API_KEY" --env UPAPI_TOOL_MODE=compact -- npx -y @upapi/mcp
```

Check: `codex 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.