MCP server setup
Connect your AI client to Crush The Market once, and it can look companies up, run screens and read filings on its own. This page is the whole setup: the command, the key, the tools and what the errors mean.
Fastest way in: paste this into the agent you want to connect and let it do the setup. It carries the command, the one flag people get wrong, and a check that proves the connection really works.
Set up the Crush The Market MCP server for me, then show me it works. 1. Run this, exactly as written, as a single line: claude mcp add --transport http crushthemarket https://crushthemarket.com/api/mcp --header "Authorization: Bearer ctm_live_YOUR_KEY" `--transport http` is required. Without it the URL is registered as a local program to spawn: the command still reports success, and it fails later at connect with `posix_spawn ENOENT`, which does not look like a setup mistake. 2. Confirm it is really connected by making a real call, not by listing tools. `tools/list` answers without a key, so a half-wrong setup can list all ten tools and still fail every call. Call `get_company` for AAPL. A working setup returns six scores, a readings block and a coverage block. 3. If the call fails, read the error rather than retrying. `missing_key` or `invalid_key` means the key did not reach the server; `email_unverified` means the account needs its email confirmed first. Tell me which it was. 4. Do not print the key back to me and do not write it into a file. It is already in this message. Then tell me, in one line, what you can do now that you could not before.Replace ctm_live_YOUR_KEY with a real key first — your account page hands you this whole prompt with the key already in it, at the moment the key is created. Prefer doing it yourself, or not using Claude Code? The rest of this page is the manual route.
What MCP is
The Model Context Protocol is a standard way for an AI client to call tools that live on somebody else's server. Point a client at this server once and the model can look a company up, run a screen or read a filing itself, instead of you pasting figures into the chat.
Our server speaks JSON-RPC 2.0 over Streamable HTTP in JSON response mode — there is no SSE stream to hold open. It answers initialize, tools/list, tools/call and ping.
Get a key first
- 1.Sign in, or register free — an email address, no card.
- 2.Verify your email address. Keys cannot be created until you have.
- 3.Open API Keys on your account page and create one. It starts
ctm_live_and is shown once, so save it there and then. Lost a key? Use Replace on the row — it revokes the old one and mints a new one in a single press.
! tools/list answers without a key, so a connection with no key or a bad one still reports every tool and looks healthy. It is the first tools/call that fails. If the tools appear but nothing works, the key is the thing to check.
Claude Code
One command. Replace ctm_live_YOUR_KEY with your own key.
> claude mcp add --transport http crushthemarket \ https://crushthemarket.com/api/mcp \ --header "Authorization: Bearer ctm_live_YOUR_KEY"! --transport http is not optional. Without it, claude mcp add <name> <arg> reads the URL as a local command to spawn, the add appears to succeed, and the connection fails later instead of now.
Check it with claude mcp list, then ask the model something it needs a tool for — "what does Crush The Market score AAPL on?" is enough.
claude.ai and other clients that cannot set headers
Some clients — the claude.ai custom connector form among them — take a URL and nothing else. For those the key goes in the path instead of a header.
https://crushthemarket.com/api/mcp/u/ctm_live_YOUR_KEY- 1.In claude.ai, open Settings, then Connectors, then Add custom connector.
- 2.Name it Crush The Market and paste the URL above with your key in it.
- 3.Save, then start a new chat — connectors are picked up per conversation.
! A key in a URL is visible in access logs, browser history and proxy logs in a way a header is not. Use the header form wherever the client allows it, and revoke a path key rather than reusing it if you ever paste that URL somewhere shared.
The tools
11 tools. Your client reads the same list from tools/list, which answers without a key:
> curl -s https://crushthemarket.com/api/mcp \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'search_companies
FreeResolves a company name or ticker to the symbols Crush The Market covers. Search reads the profile table, so a company appears here even if it has not been scored yet -- call get_company to find out. ETFs are never returned: nothing feeds us fund holdings, so they cannot be scored.
Arguments
query string, required — A company name or ticker. Matched as a prefix against both.
limit number, optional — How many results to return, 1-25. Defaults to 10.
Returns
query, count, results, error, as_of, source, disclaimer
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "search_companies", "arguments": { "query": "Apple" } }}Can answer
bad_request — `query` is empty, or is only punctuation that gets stripped.
Related: get_company, screen_stocks
get_company
FreeReturns the stored profile, the six composite scores (value, growth, financial health, dividend, management, total, each 0-100), the ranked strengths and risks, the one-line verdict per section, and a coverage block naming where the data came from and whether the filing tools will return anything for this symbol. A score of null means too few of its legs could be computed -- it is NOT a bad score.
Arguments
symbol string, required — The ticker as Crush The Market spells it. London listings carry a `.L` suffix.
Returns
symbol, profile, scores, readings, coverage, error, as_of, source, disclaimer
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "get_company", "arguments": { "symbol": "AAPL" } }}Can answer
bad_request — `symbol` is missing or empty.
unknown_symbol — No profile is held for the symbol at all.
not_covered — The symbol is an ETF. No feed supplies fund holdings, so ETFs are never scored.
no_analysis — The company is covered but has no scored row yet.
Related: search_companies, explain_metric, screen_stocks
explain_metric
FreeExplains a criterion id: its human label, the operators it accepts, the JSON type its value must have, and the written definition from the matching documentation page. Use it before screen_stocks when you are unsure what a criterion measures or how to phrase a filter. Not every criterion has a documentation page; `definition` and `explanation` are null when it does not.
Arguments
criterion_id string, required — A screening criterion id, exactly as screen_stocks accepts it.
Returns
criterion, definition, explanation, doc_url, error, as_of, source, disclaimer
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "explain_metric", "arguments": { "criterion_id": "priceToEarningsRatio" } }}Can answer
bad_request — `criterion_id` is missing or empty.
unknown_criterion — The id is not one of the published screening criteria.
Related: screen_stocks, get_company
screen_stocks
FreeRuns the same screen the website runs. `criteria` is a list of `{ id, operator, value }`, where a numeric operator is `>`, `<`, `>=` or `<=` (the word forms `More Than` / `Less Than` also work); call explain_metric for what an id means and which operators it accepts. Every response carries `universe_size` -- how many symbols in the selected markets had a scored row to filter at all. Read it before reporting an empty result: zero matches out of zero scored symbols is a coverage gap, not a finding about the market.
Arguments
criteria object[], required — Filters, each `{ "id": <criterion id>, "operator": <operator>, "value": <value> }`. A numeric criterion takes `>`, `<`, `>=` or `<=`; the word forms `More Than` and `Less Than` are accepted too, and case and surrounding spaces do not matter. `>=` and `<=` include the boundary value, `>` and `<` exclude it -- ask for the one you mean rather than nudging the number. A list criterion takes `in` or `not in` and a list of strings; a boolean criterion takes `True` or `False` and no `value`. Call explain_metric for the operators a given id accepts.
markets string[], optional — Which universes to screen. One or more of: sp500, ftse100, russell1000, ftseallshare, djia, nasdaq100. Defaults to sp500 and ftse100.
limit number, optional — How many rows to return, 1-100, highest total score first. Defaults to 25. The full match count is always in `count`.
Returns
count, universe_size, markets, results, note, query, url, url_note, error, as_of, source, disclaimer
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "screen_stocks", "arguments": { "criteria": [ { "id": "priceToEarningsRatio", "operator": "<", "value": 15 } ], "markets": [ "sp500" ] } }}Can answer
bad_request — `criteria` is empty or malformed, a criterion id is not published, an operator is not one the criterion accepts (`>=` needs a criterion that compares numerically, so a boolean or list criterion rejects it), or two criteria filter the same column.
Related: explain_metric, get_company, backtest_screen
backtest_screen
ProRebuilds the screen once per year of stored history, holds the cohort for `min_hold_years`, and reports the compound annual growth rate of the equal-weighted strategy against the equal-weighted market over the same years. Criteria and markets take the same shape as screen_stocks. `cohort_sizes` is one entry per ENTRY year, and `years` carries one more entry than that -- the trailing year the last cohort is sold in -- so do not zip the two. The figures are a property of the rows we hold, not a forecast, and a small `matched_symbols` means the result describes a handful of names.
Arguments
criteria object[], required — Filters, each `{ "id": <criterion id>, "operator": <operator>, "value": <value> }`. A numeric criterion takes `>`, `<`, `>=` or `<=`; the word forms `More Than` and `Less Than` are accepted too, and case and surrounding spaces do not matter. `>=` and `<=` include the boundary value, `>` and `<` exclude it -- ask for the one you mean rather than nudging the number. A list criterion takes `in` or `not in` and a list of strings; a boolean criterion takes `True` or `False` and no `value`. Call explain_metric for the operators a given id accepts.
markets string[], optional — Which universes to screen. One or more of: sp500, ftse100, russell1000, ftseallshare, djia, nasdaq100. Defaults to sp500 and ftse100.
min_hold_years number, optional — Whole years to hold a name before it can be dropped, 1-10. 1 is a classic yearly rebalance. Defaults to 1.
Returns
strategy_cagr, market_cagr, years, min_hold_years, cohort_sizes, matched_symbols, universe_size, markets, note, query, url, url_note, error, as_of, source, disclaimer
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "backtest_screen", "arguments": { "criteria": [ { "id": "totalScore", "operator": ">", "value": 70 } ], "markets": [ "sp500" ] } }}Can answer
requires_pro — The caller is not on an active subscription.
bad_request — `criteria` is empty or malformed, a criterion id is not published, or an operator is not one the criterion accepts (`>=` needs a criterion that compares numerically, so a boolean or list criterion rejects it).
Related: screen_stocks, explain_metric
help
FreeLong-form guidance, in topics. Call it with no argument for the essentials and the topic list, or with `topic` for one of them. Reach for it when you are unsure which tool answers a question, whether the data supports the question at all, or what an error means. It returns no company data and costs nothing but the call.
Arguments
topic string, optional — One of: start, answerable, screening, filings, scores, limits, errors, reporting. Omit for the essentials plus the topic list.
Returns
topic, title, text, topics, as_of, source, disclaimer
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "help", "arguments": { "topic": "filings" } }}Can answer
bad_request — the `topic` argument is not a string
Related: explain_metric, get_company
list_filings
FreeLists a company's filings from the SEC EDGAR submissions index, newest first, each with its accession number -- the id every other filing tool takes. `latest_annual` names the report the other tools default to. An empty list is NEVER bare: `reason` distinguishes "no SEC filer is mapped to this symbol" from "EDGAR gave us something we could not read", and `adr_symbol` names the US-listed ADR to retry against where one exists. Read `reason` before telling anyone a company files nothing.
Arguments
symbol string, required — The ticker as Crush The Market spells it. London listings carry a `.L` suffix.
form string, optional — Return only this form, matched exactly: 10-K, 10-Q, 8-K, 20-F, 40-F.
limit number, optional — How many filings to return, 1-100, newest first. Defaults to 20. The full match count is always in `total`.
Returns
symbol, count, total, filings, reason, reason_note, adr_symbol, latest_annual, note, error, as_of, source, disclaimer
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "list_filings", "arguments": { "symbol": "AAPL", "form": "10-K" } }}Can answer
bad_request — `symbol` is missing or empty.
Related: get_filing_outline, read_filing_section, score_evidence
get_filing_outline
FreeThe scan tool: call it before reading anything. Returns every addressable section of one filing -- by default the latest annual report -- across two lanes, each entry with a `section_id` for read_filing_section and a measured size so you can choose what to spend. The notes lane comes from EDGAR's own per-note rendering; read `notes.label` for what that category contains, because it is wider than the accounting notes alone. The narrative lane is regex-sectioned from the primary document and is SECOND CLASS: it carries `confidence`, `failure_reason` and `notice` at document level and `confidence`, `flags` and `notice` per section. Some filers incorporate MD&A by reference and print only a pointer where the disclosure should be; that section is flagged `incorporated_by_reference` and must not be read as the disclosure itself.
Arguments
symbol string, required — The ticker as Crush The Market spells it.
accession string, optional — A specific filing, as list_filings spells it. Defaults to the latest annual report (10-K, 20-F or 40-F).
sizes boolean, optional — Measure every note by fetching it, so `chars` and `tokens` are real rather than null. Defaults to true. Pass false for a cheaper outline when you do not need to budget.
Returns
symbol, filing, notes, narrative, note, error, as_of, source, disclaimer
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "get_filing_outline", "arguments": { "symbol": "AAPL" } }}Can answer
bad_request — `symbol` is missing, or `accession` is not in the form 0000000000-00-000000.
no_sec_filer — No SEC filer is mapped to the symbol. `adr_symbol` from list_filings may name one that is.
no_annual_report_yet — EDGAR lists filings for the issuer but no annual report among them.
unknown_filing — The accession is not one EDGAR lists for this symbol.
filing_summary_missing — EDGAR has no FilingSummary.xml for the filing, so the notes lane cannot be built.
edgar_unavailable — EDGAR did not answer, or answered with an error, after retries.
Related: list_filings, read_filing_section, search_filing, score_evidence
read_filing_section
FreeReturns the text of the section named by `section_id`, from either lane -- ids starting `note-` come from the notes lane, `item-` (or `whole-document`) from the narrative lane. THE WHOLE SECTION IS RETURNED BY DEFAULT: there is no token cap and no truncation you did not ask for. `total_chars` and `total_tokens` always describe the whole section, `chars` and `tokens` describe what came back, and `complete` says whether they are the same thing. `offset` and `limit` are opt-in; pages concatenate back into the section character for character. On a narrative section, read `section.confidence`, `section.flags` and `section.notice` before quoting -- a section flagged `incorporated_by_reference` is a pointer to another document, not the disclosure.
Arguments
symbol string, required — The ticker as Crush The Market spells it.
section_id string, required — A section id from get_filing_outline, e.g. `note-income-taxes` or `item-1a`.
accession string, optional — A specific filing. Defaults to the latest annual report.
offset number, optional — Opt-in pagination: start this many characters into the section. Omit for the whole thing.
limit number, optional — Opt-in pagination: return at most this many characters. Omit for the whole section, which is the default and the recommended call.
Returns
symbol, filing, lane, section, text, chars, tokens, total_chars, total_tokens, offset, limit, complete, truncated, page, pages_total, next_offset, is_last_page, token_estimate, note, error, as_of, source, disclaimer
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "read_filing_section", "arguments": { "symbol": "AAPL", "section_id": "note-income-taxes" } }}Can answer
bad_request — `symbol` or `section_id` is missing, `section_id` belongs to neither lane, or `offset`/`limit` are not sane numbers.
report_not_found — The notes lane has no section with that id in this filing; the message lists the ids it does have.
section_not_found — The narrative lane has no section with that id in this filing.
no_sections — The filing could not be sectioned at all, so no narrative id can be addressed. Use `whole-document`.
edgar_unavailable — EDGAR did not answer after retries.
Related: get_filing_outline, search_filing, score_evidence
search_filing
FreeLiteral, case-insensitive search across both lanes of one filing -- by default the latest annual report. Returns at most 10 hits, each about 400 characters of context and each tagged with the `section_id` it came from, so you can call read_filing_section and read the whole section rather than reasoning from a snippet. `total_matches` reports how many occurrences there were, so a returned list of ten is never mistaken for the complete set. A narrative hit carries the `confidence` and `notice` of the section it came from.
Arguments
symbol string, required — The ticker as Crush The Market spells it.
query string, required — The phrase to find, at least 3 characters. Matched literally and case-insensitively.
accession string, optional — A specific filing. Defaults to the latest annual report.
lane string, optional — Which lane to search: notes, narrative, or both. Defaults to both.
Returns
symbol, filing, query, lane, sections_searched, total_matches, count, hits, note, error, as_of, source, disclaimer
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "search_filing", "arguments": { "symbol": "AAPL", "query": "effective tax rate" } }}Can answer
bad_request — `symbol` is missing, `query` is shorter than three characters, or `lane` is not one of notes/narrative/both.
no_sec_filer — No SEC filer is mapped to the symbol.
edgar_unavailable — Neither lane could be read from EDGAR.
Related: get_filing_outline, read_filing_section
score_evidence
FreeTakes one of the six scores and returns every leg that makes it up -- the leg, its weight or axis, its value where the scoring run stored one, and the stored measurements that feed it -- each paired with the note or notes from the company's own latest annual report whose subject covers that leg, quoted inline with a `section_id` for reading the whole note. THE TOOL DOES NOT ASSERT THAT THE TEXT EXPLAINS THE NUMBER: it states where the filer writes about the subject, and the inference is yours. A leg with no sensible note returns NO note and says why in `unmapped_because` -- a forced match would have you cite an irrelevant disclosure with total confidence. The quote is capped; `section_chars` is the whole note's size and read_filing_section returns it uncapped. Where a company has no SEC filing, the legs still come back and `note` says why nothing is quoted.
Arguments
symbol string, required — The ticker as Crush The Market spells it.
score string, required — Which score to break down. One of: value_score, growth_score, financial_score, dividend_score, management_score, total_score.
accession string, optional — Take the notes from this filing rather than the latest annual report.
Returns
symbol, score, score_label, score_value, score_column, filer_family, filing, legs, leg_count, legs_with_notes, legs_without_notes, quote_chars_max, token_estimate, note, error, as_of, source, disclaimer
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "score_evidence", "arguments": { "symbol": "AAPL", "score": "management_score" } }}Can answer
bad_request — `symbol` is missing, or `score` is not one of the six score ids.
unknown_symbol — No profile is held for the symbol at all.
not_covered — The symbol is an ETF, which is never scored.
no_analysis — The company is covered but has no scored row yet.
Related: get_company, get_filing_outline, read_filing_section
One tool needs a Pro subscription: backtest_screen. Called on a free account it returns a requires_pro error naming the upgrade page, rather than a partial answer.
Ready-made prompts
The server also ships 5 prompts. Your client renders them as commands you pick — in Claude Code they appear as /crushthemarket:<name>. Each one is a sequence that is tedious to type and easy to get wrong: which tool to call first, what to check before trusting a filing section, and what the answer should look like.
| Prompt | What it does | Takes |
|---|---|---|
company_briefing | Full workup on one company: the scores, and what in its own filing explains them. | symbol |
why_this_score | Tie one score to the sentences in the company's annual report that justify it. | symbol, score (optional) |
run_a_screen | Build and run a stock screen from a description, then explain what survived. | criteria, markets (optional) |
read_the_filing | Scan a company's annual report and answer a question from what it actually says. | symbol, question |
compare_companies | Compare two or more companies on the same footing, and say what actually differs. | symbols, focus (optional) |
A prompt is picked by a person, so nothing that stops an agent going wrong lives only there — those rules are in the tool descriptions and in the help tool, which an agent finds on its own through tools/list. prompts/list and prompts/get answer without a key, because a prompt describes the interface rather than returning data from it.
The allowance, and the pace limit
- —Free — 12 tool calls per 16 hours. Its own allowance: the 12 screening and search actions the website gives you are counted separately.
- —Pro — no call limit.
- —Every successful call carries a
quotablock withused,limitandreset_at, so the model can see how much room is left without asking. With two calls or fewer remaining the response also carries anoticesaying so. - —Separately: 60 calls a minute and 5,000 a day per key. That is a pace limit, it refills continuously, and Pro does not lift it.
What an error looks like
There are two shapes, and the difference matters because they need different responses.
A transport failure — the call never ran — comes back as a JSON-RPC error with code -32001 and the real reason in error.data.code:
{ "jsonrpc": "2.0", "id": 2, "error": { "code": -32001, "message": "This account's free allowance of 12 agent calls is used up until 14:30 UTC. Pro removes the limit: https://crushthemarket.com/subscribe", "data": { "code": "quota_exhausted" } }}| data.code | What happened | What to do |
|---|---|---|
missing_key | No key on the connection. | Reconnect with a key; see above. |
invalid_key | Unknown, mistyped or revoked key. | Create a new key on your account page. |
email_unverified | The account's email address is not verified. | Request a new verification email from your account page. |
requires_pro | The tool needs a Pro subscription. | Upgrade, or use a free tool. |
quota_exhausted | The free allowance is spent. | Wait for reset_at, or upgrade. Retrying sooner will not help. |
rate_limited | Too fast for the pace limit. | Wait the seconds named in the message and retry. |
bad_request | Unknown tool name, or a bad argument. | Re-read tools/list and retry with a name and arguments from it. |
internal | The server failed. | Retry once. The message never carries a stack or an upstream URL. |
A lookup that simply missed is not an error at the protocol level. The call succeeded and the answer says so, in the body, with isError false:
{ "error": { "code": "unknown_symbol", "message": "No company matches that symbol." }, "as_of": "2026-09-27", "source": "Crush The Market", "disclaimer": "Data, not advice. Do your own diligence."}That is deliberate: an MCP client shows the model the body and never the status line, so an error that lived only in the status would be one the model could not read or relay. Codes that arrive this way are unknown_symbol, not_covered, no_analysis, unknown_criterion and bad_request.
Machine-readable
- —/.well-known/mcp.json — the server descriptor. Public, no key.
- —/openapi.json — the same tools as a REST contract. Public, no key.
- —
tools/listonhttps://crushthemarket.com/api/mcp— the live schemas.
All of them, and this page, are generated from one registry. Not a chat client? The REST API exposes the same tools over ordinary HTTP.
More for agents
Data, not advice. Do your own diligence.