Claude Code

Paste the sentence below into Claude Code 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.

1. Run:

   claude mcp add --scope user --transport http upapi https://app.upapi.io/api/mcp

2. You do this: In Claude Code, run /mcp, select upapi and choose Authenticate. A browser opens to sign in to upAPI. No restart is needed.

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.

1. Run:

   claude mcp add --scope user upapi --env UPAPI_API_KEY="$UPAPI_API_KEY" --env UPAPI_TOOL_MODE=compact -- npx -y @upapi/mcp

Check: claude mcp list shows upapi as Connected (or Needs authentication until the user signs in).

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.