MCP Server

The scanr.ai MCP (Model Context Protocol) server lets you drive scanr.ai from Claude, Cursor, or any MCP-compatible client. One bearer token, zero glue code, your existing API tier — same limits, same billing as the REST API.

New — 8 tools live, including AI-driven natural-language scan generation.

What it is

The Scanr MCP server speaks the Model Context Protocol over a single HTTP endpoint:

POST https://mcp.scanr.ai

Connect an MCP client and your assistant can scan the U.S. equities universe, resolve securities, fetch news, surface trending stocks, run AI-generated screens, and more — all metered against the API tier you already pay for.

Two tools (natural_scan, refine_payload) use scanr.ai's natural-language RAG pipeline and count against your daily AI quota; the remaining six are direct passthroughs that only count against per-minute / hour / day request limits.

Data boundary. The MCP surface returns scan results, reference data, news, and lean trending-symbol lists. It does not expose raw OHLCV bars, company fundamentals / financial statements, or real-time quotes — use the scanr.ai web app for those. Each tool also enforces a minimum API tier (all tools are Starter today).

1. Get an API token

You'll need an active API subscription (Starter tier or higher) and a bearer token.

1. Sign in to scanr.ai.
2. Go to Account → API Tokens.
3. Create a token with the read scope.
4. Copy it — it's shown only once.

Pass it on every MCP request as Authorization: Bearer scanr_....

See Authentication for the full token lifecycle (rotation, revocation, scopes).

2. Connect your client

Claude Code (CLI)

One command — persists to your local Claude Code config:

claude mcp add --transport http scanr \
  https://mcp.scanr.ai \
  --header "Authorization: Bearer scanr_..."

After running this, open Claude Code and type /mcp to confirm the scanr server is connected and listing tools.

Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config) and restart Claude:

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

Cursor

Add to ~/.cursor/mcp.json:

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

Any other MCP client

The endpoint speaks standard MCP over Streamable HTTP — point any compliant client at https://mcp.scanr.ai with the same Authorization: Bearer scanr_... header.

3. Available tools

All tools share a common contract: bearer-auth, per-tool rate limits, tool-level errors for rate-limit / validation failures, and BigInt-safe JSON serialization.

Each tool declares a minimum API tier that is enforced per call — a below-tier token gets a tool-level error before the handler runs. All tools are Starter today.

Tool descriptions and input schemas are served via the standard tools/list JSON-RPC call — your MCP client will discover them automatically on first connect, so the LLM always sees the up-to-date contract.

Recommended flow for "find me stocks like X"

1. natural_scan with a free-text description.
2. (optional) refine_payload to tweak filters via natural language.
3. scan on the returned generated_payload / refined_payload to execute.

Building a ScannerPayload from scratch is hard — prefer this flow over hand-encoding filters unless the request is trivial.

4. Rate limits

Each tool gets its own per-minute / hour / day Redis bucket per user, matching the limits on your REST API tier. Hitting any window returns a tool-level error (not an HTTP 500), so your assistant can recover gracefully.

AI-metered tools (natural_scan, refine_payload) additionally consume your daily UI AI quota — same bucket as the natural-search feature in the scanr.ai web UI. Hitting it returns a tool-level error explaining the cap and a hint to upgrade.

The MCP handshake (initialize, tools/list) is not rate-limited.

5. Authentication & error model

• Auth failures (missing/invalid/expired token, below the Starter minimum, missing scope) → MCP returns a 401 with WWW-Authenticate metadata, before any tool is invoked.
• Below a tool's minimum tier → the tool call returns { isError: true, content: [{ type: "text", text: "..." }] } explaining the required tier. Not an HTTP 500. (All tools are Starter today, so this only triggers if a higher-tier tool is added.)
• Per-tool rate limit exceeded → the tool call returns { isError: true, content: [{ type: "text", text: "..." }] } with an explanation. Not an HTTP 500.
• AI quota exceeded (AI-metered tools only) → same tool-level error format.
• Validation errors (e.g. unsupported intraday timeframe on a free UI tier) → tool-level error with a human-readable message.
• Unexpected internal errors → tool-level error with a generic message; details are logged server-side.

Usage is tracked per-tool under the path /api/mcp/tools/<toolName> for billing and analytics.

6. Calling without an MCP client

If you don't want a managed client, MCP is just JSON-RPC over HTTP. Here's a minimal tools/call against search_securities:

curl -X POST https://mcp.scanr.ai \
  -H "Authorization: Bearer scanr_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_securities",
      "arguments": { "q": "Apple", "l": 5 }
    }
  }'

To discover the tool set programmatically, swap tools/call for tools/list and drop the arguments field.

Need help?

Found a bug, missing a tool, or want a higher-tier feature exposed via MCP? Email contact@bagsbydata.com. The REST endpoints documented in the API Reference cover the same underlying data the MCP tools return — useful for spot-checking responses.