# Cursor (https://upapi.io/docs/agent-setup/cursor)



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

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

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

2. **User step:** 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.

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

```json
{
  "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

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.