---
name: scanr-setup
description: Connect an AI agent to scanr.ai through its MCP server or REST API, then run a first live stock scan.
---

# Connect to scanr.ai

Help the user connect to scanr.ai and get one live scan working.

scanr.ai is a stock scanner for U.S. equities. One request screens every U.S.-listed stock on price, volume, 100+ technical studies, fundamentals, relative strength, and candlestick and chart patterns, and returns the tickers that match. It also serves the data behind the scanner: relative strength ranks, chart patterns, supply/demand zones, market themes, news and 80+ technical indicators.

There are two ways in, both using the same token, plan and limits:

- **MCP server** (recommended for chat and coding assistants, nothing to build): `https://mcp.scanr.ai`, Streamable HTTP, authenticated with an `Authorization: Bearer scanr_...` header. Tools: `natural_scan`, `refine_payload`, `scan`, `search_securities`, `market_status`, `get_news`, `hot_tickers`, `concept_research` (Power User plan+), `ping`.
- **REST API** (scripts, notebooks, the user's own backend): base URL `https://scanr.ai/api/v2`, same Bearer header.

How to choose:

- Using Claude Code, Claude Desktop, Cursor, VS Code or Codex? Go MCP.
- Writing a script or calling from their own code? Go REST.
- Using claude.ai or ChatGPT custom connectors? Those only support OAuth sign-in, which the MCP server doesn't offer yet. Suggest Claude Desktop or Claude Code instead, or REST.

Ask which client they're using rather than guessing, and recommend one. If they just want the fastest path, suggest MCP.

## 1. Get a token

The MCP server has no OAuth sign-in and there is no signup API: the user creates the token themselves, in the browser.

1. They need an API plan. Every plan includes the full scanner and MCP. Plans: https://scanr.ai/api-pricing
2. They create a token at https://scanr.ai/account/api-tokens with the `read` scope. It is shown once. Suggest a name that says what it's for (`claude-code`, `cursor`), so it's easy to find and revoke later.
3. The safest hand-off is an environment variable, which every command below reads:

```bash
export SCANR_API_TOKEN="scanr_..."
```

Handle the token with care. Prefer that the user sets the variable or edits the config file themselves. If they paste the token into the conversation, use it only to write the config, never repeat it back, never put it in a URL, and don't commit it to a repository.

## 2. Connect the MCP server

### Claude Code

```bash
claude mcp add --transport http scanr https://mcp.scanr.ai \
  --header "Authorization: Bearer $SCANR_API_TOKEN"
```

Add `--scope project` to share it through the repository's `.mcp.json`; then keep the token in an environment variable, not in the file. Verify with `claude mcp list`, or `/mcp` inside Claude Code. A new server's tools appear in a new session.

### Claude Desktop

Settings → Developer → Edit Config opens `claude_desktop_config.json`. Add:

```json
{
  "mcpServers": {
    "scanr": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.scanr.ai",
        "--header",
        "Authorization:${SCANR_AUTH}"
      ],
      "env": {
        "SCANR_AUTH": "Bearer scanr_..."
      }
    }
  }
}
```

Claude Desktop reaches remote servers with headers through the `mcp-remote` bridge, which needs Node.js. Quit and reopen Claude Desktop after saving.

### Cursor

Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project), then save and restart Cursor:

```json
{
  "mcpServers": {
    "scanr": {
      "url": "https://mcp.scanr.ai",
      "headers": {
        "Authorization": "Bearer scanr_..."
      }
    }
  }
}
```

### VS Code

Add to `.vscode/mcp.json` in the workspace. VS Code asks for the token once and stores it securely:

```json
{
  "servers": {
    "scanr": {
      "type": "http",
      "url": "https://mcp.scanr.ai",
      "headers": {
        "Authorization": "Bearer ${input:scanr-token}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "scanr-token",
      "description": "scanr.ai API token",
      "password": true
    }
  ]
}
```

### Codex

Add to `~/.codex/config.toml`, and export `SCANR_API_TOKEN` in the shell that starts Codex:

```toml
[mcp_servers.scanr]
url = "https://mcp.scanr.ai"
bearer_token_env_var = "SCANR_API_TOKEN"
```

### Any other MCP client

Point it at `https://mcp.scanr.ai` over Streamable HTTP with the header `Authorization: Bearer scanr_...`. It does not accept `X-API-Key`.

Most clients load MCP servers only at startup. After adding the server, tell the user to restart the client or open a new chat, and wait for them before continuing.

## 3. Run a first scan

Once connected, run one real query end to end so the user sees it work:

1. Call `ping` to confirm the connection and the token.
2. Call `market_status`, so you can say whether the market is open (intraday scans read provisional bars).
3. Call `natural_scan` with a plain-English screen, for example *"large caps above their 200-day moving average with RSI(14) under 40"*. Show the user `reasoning.summary`, the one-line description of what will be screened.
4. Call `scan` with the returned `generated_payload` as `instructions`. Report the count and the first few tickers.
5. Offer a follow-up: `refine_payload` to adjust the screen (*"only NASDAQ"*, *"use the weekly chart"*), or `get_news` / `search_securities` on the top matches.
6. If the user already has scans in the scanr.ai scanner, tell them they can bring one over: **Filters → Export filters → Copy to clipboard**, then paste it. Run it with `scan` unchanged.

`natural_scan` and `refine_payload` spend the plan's daily AI credits; running a payload with `scan` doesn't. Keep payloads the user likes and re-run them. Never write a payload from scratch when `natural_scan` or an exported scan can supply one.

## REST setup

With the token in `SCANR_API_TOKEN`, check it works:

```bash
curl https://scanr.ai/api/v2/misc/market-status \
  -H "Authorization: Bearer $SCANR_API_TOKEN"
```

Then turn a sentence into a scan payload, and run it:

```bash
curl https://scanr.ai/api/v2/scan/natural \
  -H "Authorization: Bearer $SCANR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "large caps above their 200-day moving average with RSI(14) under 40"}'
```

`POST /scan/natural` returns `generated_payload` and does not run it. Send it on to `POST /scan` as `{"instructions": <generated_payload>}`, which returns the matching `tickers` and their `count`. The full walkthrough, in cURL, Python and JavaScript: https://api-docs.scanr.ai/quickstart.md

## If something breaks

- **Tools missing after adding the server:** restart the client or open a new chat, then retry.
- **`401`:** the token is missing, malformed, revoked or expired, or it was sent as `X-API-Key` to the MCP server. The JSON body's `error_description` says which. Create a new token if it was revoked.
- **`403`:** the token lacks the `read` scope, or the account has no active API plan.
- **`406` when calling MCP with `curl`:** send `Accept: application/json, text/event-stream`.
- **`429` or a rate-limit tool error:** wait at least a minute; don't retry in a loop. AI credits reset at 00:00 UTC.
- **`scan` says personal data access is disabled:** the user switched off API-token access to account data in their scanr.ai settings; the other tools keep working.

## Next

- Install the scanr.ai Agent Skill so you write correct scan payloads: https://api-docs.scanr.ai/skill.md
- Every docs page as markdown, starting from the index: https://api-docs.scanr.ai/llms.txt
- MCP server reference (tools, limits, errors): https://api-docs.scanr.ai/mcp-server.md
- Help: contact@bagsbydata.com