MCP Server

The scanr.ai MCP server gives an AI assistant the scanner as a set of tools. Connect Claude, Cursor, VS Code or any other Model Context Protocol client, and it can turn "find me beaten-down large caps that are starting to turn" into a scan, run it, and look up what it found. It uses your API token and plan, with the same limits and billing as the REST API.

https://mcp.scanr.ai

Before you start

You need an API plan (every plan includes MCP) and a token with the read scope from Account → API Tokens. Give the assistant its own token so its usage is easy to see and to revoke. See Authentication.

Connect your client

Where each configuration goes:

• Claude Code: the command saves it to your Claude Code config. Add --scope project to share it through the repository's .mcp.json (then use an environment variable, not a pasted token).
• Claude Desktop: Settings → Developer → Edit Config opens claude_desktop_config.json. Claude Desktop connects to remote servers with headers through the mcp-remote bridge, which needs Node.js. Restart Claude after saving.
• Cursor: ~/.cursor/mcp.json, or .cursor/mcp.json in a project.
• VS Code: .vscode/mcp.json in the workspace. VS Code asks for the token once and stores it securely.
• Codex: ~/.codex/config.toml; export SCANR_API_TOKEN in the shell that starts Codex.
• Any other client: point it at https://mcp.scanr.ai over Streamable HTTP with the Authorization header.

Tools

Every tool is available on every plan except concept_research, which needs Power User or Business (and is rolling out account by account). Each result is a single text block of JSON; very large numbers arrive as strings.

get_news returns a cursor with each page. For the next, older page, call it again with the same ticker, page: "prev", from_time set to the result's prev_time and from_id set to its ceiling_id. An empty news list means there are no more.

concept_research answers "does XMPL relate to rare earths?" with ticker, and "which stocks relate to rare earths?" without it. unknown is not a no, and an empty partial list means "none among the candidates asked", not "none"; each result's meaning says which, and a refusal comes back as a result with ok: false and a code. See Research a Concept.

The MCP tools cover scanning, reference data, news and concept research. For relative strength, chart patterns, themes, zones and technical indicators, call the REST API, which serves them to the same token.

How an assistant should scan

Scan payloads are detailed JSON, and a model writing one from scratch tends to get plot names and comparators wrong. So the assistant shouldn't write one. It gets a payload, then runs it:

1. Get a payload, one of two ways:
   • natural_scan with the user's description. Show the user reasoning.summary and the filter list, so they can see what will be screened.
   • An exported scan. If the user already has the screen in the scanr.ai scanner, they click Filters → Export filters → Copy to clipboard and paste the JSON into the chat. Use it as it is. It costs no AI credits and is exactly the screen they already trust.
2. refine_payload for each correction the user asks for ("only large caps", "use the weekly chart"). It keeps the filters that are already right, and works on an exported payload as well as a generated one.
3. scan with the final payload as instructions.
4. Enrich, then answer. Use search_securities or get_news on the top matches, or REST data endpoints for relative strength and patterns, before summarizing.

Keep the final payload. Re-running it with scan costs one request and no AI credits, while calling natural_scan again costs credits and may produce a slightly different screen.

The payloads in these docs' guides are written out in full so you can see what they screen. To run one through an assistant, give it the guide's sentence and let natural_scan build the payload, or paste the JSON and ask it to call scan with it unchanged.

If the assistant writes a payload itself, point it at Building Scan Payloads (or /scan-payloads.md), or install the Agent Skill, which carries the same rules.

Limits

• Requests: each tool has its own per-minute, per-hour and per-day limits, equal to your plan's REST limits (30/min on Starter; see Plans & Rate Limits) and separate from the REST endpoints' counters. Connecting and listing tools doesn't count.
• AI credits: natural_scan and refine_payload spend your plan's daily AI credit budget, shared with the REST natural-language endpoints and reset at 00:00 UTC.
• Size: requests are limited to 1 MiB. Scan results aren't truncated, so a broad scan can return thousands of tickers; narrow the payload rather than asking the model to page through them.

Errors

• Authentication fails before any tool runs, with a JSON body whose error_description says what went wrong:
  • 401 for a missing token, a token sent as X-API-Key, or a token that is malformed, revoked or expired;
  • 403 for a token without the read scope, or an account whose API plan is inactive;
  • 503 when the plan couldn't be checked. Retry it.
• Everything else is a tool result with isError: true and a message the assistant can read and act on: a rate limit (with the window that ran out), the AI credit budget, personal data access being off, an invalid payload, or an argument that failed validation.

Scans run from MCP are recorded in your scan history like any other. If you switch off personal data access for API tokens, scan returns an error saying so; the other tools keep working.

Calling it without a client

MCP is JSON-RPC over HTTP, so you can call a tool with curl. The server is stateless: no session to open, one POST per call. Send both Accept types, or the server answers 406:

curl https://mcp.scanr.ai \  -H "Authorization: Bearer $SCANR_API_TOKEN" \  -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": "nvidia", "l": 3 }    }  }'

The reply arrives as a server-sent event:

event: messagedata: {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"{\n  \"count\": 3, ..."}]}}

Swap the method for tools/list (and drop params) to list the tools and their input schemas.

Need help?

Found a bug, or need a tool the server doesn't have? Email [email protected].