# VS Code (https://upapi.io/docs/agent-setup/vscode)



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

## VS Code

### 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 `.vscode/mcp.json`. VS Code uses `servers`, not `mcpServers`. Add the `upapi` entry to an existing `servers` object and keep everything else. The file holds no secret, so it is safe to commit.

```json
{
  "servers": {
    "upapi": {
      "type": "http",
      "url": "https://app.upapi.io/api/mcp"
    }
  }
}
```

2. **User step:** In VS Code, open `.vscode/mcp.json`, click Start above the `upapi` entry and allow the sign-in. 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 `.vscode/mcp.json`. The key comes from a prompted input, never the file, because `.vscode/mcp.json` is usually committed. Merge into `inputs` and `servers` without dropping existing entries.

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "upapi-key",
      "description": "upAPI API key",
      "password": true
    }
  ],
  "servers": {
    "upapi": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@upapi/mcp"
      ],
      "env": {
        "UPAPI_API_KEY": "${input:upapi-key}",
        "UPAPI_TOOL_MODE": "compact"
      }
    }
  }
}
```

Check: The `upapi` entry in `.vscode/mcp.json` shows Running.

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