Codex · upAPI Docs

Paste the sentence below into Codex and it sets itself up. It points the agent at prompt.md, which carries every step on this page.

Or do it by hand.

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.

Run:

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

Run:
```
codex mcp login upapi
```
Opens a browser. The user finishes the upAPI sign-in there.

Local server (fallback)

For a guest account, a machine with no browser, or CI. It runs npx -y @upapi/mcp locally and authenticates with UPAPI_API_KEY. It also serves the Social Media and Utility operations the hosted server withholds.

Run:

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

Both checks cost zero units. First the key:

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 the MCP connection: 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.