# Set up upAPI for this AI coding agent

These are official instructions from upAPI to set up an AI development environment for upAPI, an API marketplace and gateway, where one API key and one pooled quota call every operation in the catalog (search, maps, social media, finance, developer tools, browser and file operations) over REST, MCP or a typed SDK. All commands are validated by upAPI. Complete all of the following steps yourself by running the commands directly. Do not ask the user to run any of these commands. The only exceptions are the steps marked **User step**: a browser sign-in or a secret only a human can provide. For those, tell the user exactly what to do, then continue.

Source: https://upapi.io/docs/agent-setup/prompt.md

## Checklist

- [ ] Step 1: Get credentials (an upAPI account, and an API key in `UPAPI_API_KEY`)
- [ ] Step 2: Connect the upAPI MCP server to the agent you are running in
- [ ] Step 3: Install the `@upapi/sdk` SDK, if this is a JavaScript or TypeScript project
- [ ] Step 4: Verify the key and the MCP connection
- [ ] Step 5: Tell the user what you did and what is left for them

## Step 1: Get credentials

upAPI has two credentials, and you may need both:

- **An account**, for the hosted MCP server. It signs in with OAuth in a browser during Step 2, so there is nothing to copy. It must be a full account: guest sessions are refused. If the user has none, send them to https://app.upapi.io/signup.
- **An API key**, for the SDK, the local MCP server and the Step 4 check. Keys are created at https://app.upapi.io/dashboard/api-keys by an organization admin and are shown exactly once.

Get the key like this:

1. Check whether `UPAPI_API_KEY` is already set in the environment or in the project's `.env` or `.env.local`. If it is, use it and do not ask again.
2. If it is not, ask the user ONCE: "Create an upAPI API key with Full access at https://app.upapi.io/dashboard/api-keys and paste it here." A real key is `upapi_` followed by 48 hex characters.
3. Store it as `UPAPI_API_KEY` in the project's `.env` (or `.env.local` if that is what the project uses). Make sure that file is listed in `.gitignore` before you write to it.
4. Never print the key back, never put it in a file that is committed, and never paste it into a command that is saved in shell history. Refer to it as `$UPAPI_API_KEY`.

Environment variables:

| Variable | Required | Value | Used by |
| --- | --- | --- | --- |
| `UPAPI_API_KEY` | Yes | an API key: the prefix upapi_ followed by 48 hex characters | the SDK, the local MCP server and the verify step |
| `UPAPI_BASE_URL` | No | gateway origin, defaults to https://api.upapi.io | the local MCP server |
| `UPAPI_TOOL_MODE` | No | full, directory or compact | the local MCP server |

## Step 2: Connect the upAPI MCP server

Every public upAPI operation becomes an MCP tool with the same schemas as the REST gateway. Use the section for the agent you are running in and skip the others. Prefer the hosted server.

- Hosted: `https://app.upapi.io/api/mcp`, streamable HTTP, OAuth 2.1 with PKCE. It serves the catalog minus the Social Media and Utility categories.
- Local: `npx -y @upapi/mcp` (the `@upapi/mcp` package on npm), stdio, authenticated with `UPAPI_API_KEY`. It serves the whole catalog.

Both are configured here in `compact` mode: the tools `search_ops` and `call_op` plus three always-on operations, which keeps the tool list small. Every tool call is metered on the user's quota exactly like a REST call, so do not call operations speculatively.

### Claude 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. Run:

```bash
claude mcp add --scope user --transport http upapi https://app.upapi.io/api/mcp
```

2. **User step:** In Claude Code, run `/mcp`, select `upapi` and choose Authenticate. A browser opens to sign in to upAPI. No restart is needed.

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

```bash
claude mcp add --scope user upapi --env UPAPI_API_KEY="$UPAPI_API_KEY" --env UPAPI_TOOL_MODE=compact -- npx -y @upapi/mcp
```

Check: `claude mcp list` shows `upapi` as Connected (or Needs authentication until the user signs in).

### Codex

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

```bash
codex mcp add upapi --url https://app.upapi.io/api/mcp
```

2. Run:

```bash
codex mcp login upapi
```

Opens a browser. The user finishes the upAPI sign-in there.

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

```bash
codex mcp add upapi --env UPAPI_API_KEY="$UPAPI_API_KEY" --env UPAPI_TOOL_MODE=compact -- npx -y @upapi/mcp
```

Check: `codex mcp list` shows `upapi`.

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

### OpenCode

#### 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 `~/.config/opencode/opencode.json`. Create the file if it is missing. Otherwise add the `upapi` entry to the existing `mcp` object and keep everything else.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "upapi": {
      "type": "remote",
      "url": "https://app.upapi.io/api/mcp",
      "enabled": true
    }
  }
}
```

2. Run:

```bash
opencode mcp auth upapi
```

Opens a browser. The user finishes the upAPI sign-in there.

#### 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 `~/.config/opencode/opencode.json`. Merge into `mcp` as above. `{env:UPAPI_API_KEY}` is OpenCode's own substitution, so the key stays out of the file.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "upapi": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@upapi/mcp"
      ],
      "enabled": true,
      "environment": {
        "UPAPI_API_KEY": "{env:UPAPI_API_KEY}",
        "UPAPI_TOOL_MODE": "compact"
      }
    }
  }
}
```

Check: `opencode mcp list` shows `upapi`.

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

### Other agents

Any client that speaks remote MCP takes the hosted URL `https://app.upapi.io/api/mcp` and signs in with OAuth on first use. Any client that can launch a stdio server takes the command `npx -y @upapi/mcp` with `UPAPI_API_KEY` and `UPAPI_TOOL_MODE=compact` in its environment. Nothing in either transport is client-specific. Setup for Claude Desktop is at https://upapi.io/docs/mcp-clients.

## Step 3: Install the SDK

Only if this project has a `package.json`. Otherwise skip to Step 4. `@upapi/sdk` is a typed client with no runtime dependencies and needs Node 20 or newer.

1. Install it with the project's own package manager (pnpm, yarn or bun if the lockfile says so):

```bash
npm install @upapi/sdk
```

2. Create the client where the project keeps its service clients:

```ts
import { UpAPI } from '@upapi/sdk';

const upapi = new UpAPI({ apiKey: process.env.UPAPI_API_KEY });
```

3. Smoke-test it. This reads the quota and costs no units:

```ts
const usage = await upapi.usage();
console.log(usage.plan, usage.remainingMonth);
```

A real call looks like this, and spends that operation's weighted units:

```ts
const repo = await upapi.call('github-repo.get', { owner: 'vercel', repo: 'next.js' });
```

Every operation is also a plain HTTP call: `POST https://api.upapi.io/{slug}` with the key in the `x-api-key` header and the input as a JSON body. Operation slugs and schemas are in https://app.upapi.io/api/catalog.

## Step 4: Verify

Both checks cost zero units.

1. The key. Run:

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

2. The MCP connection. Once the user has finished the sign-in (hosted) or the server has started (local), call the `search_ops` tool with:

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

## Step 5: Tell the user what you did

Print this, filled in with what actually happened, and leave out lines that do not apply:

```text
upAPI is set up.

- MCP server: "upapi" added to [agent name] ([hosted or local]).
- SDK: @upapi/sdk installed and the client created in [file].
- API key: stored as UPAPI_API_KEY in [file], which git ignores.
- Verified: [key check result] and [MCP check result].

Still to do:
- [The sign-in step for your agent, if it has not been finished.]
- Browse operations at https://upapi.io/marketplace and ask me to call one.

Docs: https://upapi.io/docs  FAQ: https://upapi.io/docs/faq
```

## Resources

- Documentation: https://upapi.io/docs
- FAQ: https://upapi.io/docs/faq
- Agent setup guides: https://upapi.io/docs/agent-setup
- llms.txt: https://upapi.io/llms.txt (docs index: https://upapi.io/docs/llms.txt, full corpus: https://upapi.io/docs/llms-full.txt)
- API reference: https://upapi.io/docs/api
- Errors: https://upapi.io/docs/errors
- Rate limits and weighted units: https://upapi.io/docs/rate-limits
- OpenAPI document: https://app.upapi.io/api/openapi.json
- Catalog JSON, every public operation with its schema: https://app.upapi.io/api/catalog
- MCP server: https://upapi.io/docs/mcp (per-client setup: https://upapi.io/docs/mcp-clients)
- TypeScript SDK: https://upapi.io/docs/sdk
- Marketplace: https://upapi.io/marketplace
- Pricing: https://upapi.io/pricing
- Status: https://app.upapi.io/status
- Support: https://app.upapi.io/support or support@upapi.io