Cursor

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 ~/.cursor/mcp.json. Create the file if it is missing. Otherwise add the upAPI entry to the existing mcpServers object and keep every other entry.

   {
     "mcpServers": {
       "upAPI": {
         "url": "https://app.upapi.io/api/mcp"
       }
     }
   }

2. You do this: In Cursor's MCP settings, sign in on the upAPI entry (Cursor also asks the first time a tool is used). A browser opens to sign in to upAPI.

Or install it in one click: Add upAPI to Cursor.

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.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 ~/.cursor/mcp.json. Merge into mcpServers as above. ${env:UPAPI_API_KEY} is Cursor's own interpolation, so the key stays out of the file. Cursor must be started from an environment where UPAPI_API_KEY is set.

   {
     "mcpServers": {
       "upAPI": {
         "command": "npx",
         "args": [
           "-y",
           "@upapi/mcp"
         ],
         "env": {
           "UPAPI_API_KEY": "${env:UPAPI_API_KEY}",
           "UPAPI_TOOL_MODE": "compact"
         }
       }
     }
   }

Check: Cursor Settings lists upAPI under MCP with its tools enabled.

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.