Cursor · upAPI Docs

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

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

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.