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.

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

2. You do this: 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)

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

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

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.