# Set up ScaledPapers for your AI coding agent

These are the official instructions for connecting an agent to ScaledPapers. Complete the steps yourself. Ask the user only for the API key, and only once.

Canonical copy: https://scaledpapers.com/agent-setup/prompt.md. Human guide: https://scaledpapers.com/docs/mcp/.

## Checklist

1. Install the skill (once per machine): `npx skills add ScaledPapers/skills --skill scaledpapers -a claude-code -a codex -g -y`
2. Identify which coding agent you are. Run `bash ~/.agents/skills/scaledpapers/scripts/wire-mcp.sh` with `cursor`, `claude`, or `codex` to register MCP, or use the manual snippet in the matching section below.
3. If `SP_API_KEY` is already set, keep it. Otherwise ask once for a key and export it.
4. Call the `usage` tool and confirm it returns this workspace’s plan.
5. Print the completion message.

Catalog: https://www.skills.sh/scaledpapers/skills/scaledpapers

## What you are connecting

ScaledPapers monitors HTTP, API, DNS, and TCP checks and publishes status pages. The MCP server is remote Streamable HTTP at `https://api.scaledpapers.com/mcp`. It authenticates with a workspace API key sent as `Authorization: Bearer`. It does not use OAuth.

The server exposes 31 named tools, including `usage`, `list_checks`, `create_check`, `run_check`, and `create_status_page`. Call `usage` before creating a check or a page. Stop when a cap is reached (`endpoints_used` against `max_endpoints`, or the status-page cap).

claude.ai, Claude Desktop, and ChatGPT are not supported. They expect OAuth. Do not invent a connector, a stdio package, or an OAuth client.

## Get the key

Check the environment first. If `SP_API_KEY` is set and starts with `sp_`, use it and skip the rest of this section.

Otherwise ask the user once. An owner or admin creates the key at https://scaledpapers.com/app/api-keys and pastes the secret back. Export it as `SP_API_KEY` in the shell. Never write the raw key into a file that is committed, and never print it back.

## Configure your agent

Use the section that matches the agent you are. Skip the others. The URL is always `https://api.scaledpapers.com/mcp`.

### Cursor

Merge this into `~/.cursor/mcp.json`, keeping any existing `mcpServers` entries:

```json
{
  "mcpServers": {
    "scaledpapers": {
      "url": "https://api.scaledpapers.com/mcp",
      "headers": { "Authorization": "Bearer ${env:SP_API_KEY}" }
    }
  }
}
```

### Claude Code

Run:

```bash
claude mcp add --transport http scaledpapers https://api.scaledpapers.com/mcp \
  --header "Authorization: Bearer ${SP_API_KEY}"
```

### Codex

Merge this into `~/.codex/config.toml`:

```toml
[mcp_servers.scaledpapers]
url = "https://api.scaledpapers.com/mcp"
bearer_token_env_var = "SP_API_KEY"
```

## Verify

Call the `usage` tool with no arguments. Success is a JSON object that includes `plan`, `endpoints_used`, and `max_endpoints`. A 401 means the key is missing, revoked, or not an `sp_` key: ask the user to create a new key and export it again. Do not create checks during this check.

## Completion message

When the steps above are done, print this, filled in:

```text
ScaledPapers is connected to <agent name>.

- MCP server: https://api.scaledpapers.com/mcp
- API key: exported as SP_API_KEY
- Verified with: usage (<plan>, <endpoints_used> of <max_endpoints> checks)

You may need to reload MCP servers before the tools appear. Ask the agent to watch the health URLs in this repo when you want checks created.
```

## After setup

The human guide at https://scaledpapers.com/docs/mcp/ describes checks, status pages, incidents, maintenance, and what stays in the console. Team, billing, creating API keys, and creating alert destinations stay in the console.