What NewsCatcher is
NewsCatcher is news search and news research for agents, in every language. It has two products, behind one account, one credit balance and one MCP server:- News API: answers in seconds. Ranked articles grouped into stories for the last 30 days, or every article that matches a boolean query over the last 12 months.
- Agent API: research that takes minutes and returns a table. Every event of a kind (deals, layoffs, recalls…) with its sources, or the news stories of each company in a list. Monitors repeat it on a schedule.
Which tool to use
Use
search_news when the top results are enough. Use list_articles when you
need every match. Use an agent run when the person needs
a list in which every row is checked against its sources.
Step 1: connect
The MCP server ishttps://mcp.newscatcherapi.com/mcp (streamable HTTP).
Connect in one of two ways.
Sign in (preferred). Add the server URL with no key. The client asks the
person to sign in to their NewsCatcher account and approve access; there is
no key to copy. This needs a client that supports sign-in for remote MCP
servers, such as Claude.ai, Claude Desktop and Claude Code, and a person to
complete it: you cannot finish it alone.
- Claude Code: run
claude mcp add --transport http newscatcher https://mcp.newscatcherapi.com/mcp, then ask the person to run/mcp, picknewscatcherand choose Authenticate. - Claude.ai and Claude Desktop: the person adds a custom connector under Settings > Connectors with the URL above, leaves the OAuth fields empty, and clicks Connect.
x-api-key: YOUR_API_KEYheader (use this when the client has a headers field)Authorization: Bearer YOUR_API_KEYheader?apiKey=YOUR_API_KEYon the server URL, only for clients with no headers field (the key can end up in logs)
x-api-key header. The exact config
file for each is on the MCP server
page.
No MCP support? Call the REST APIs directly with the same key in the
x-api-key header:
- News API:
https://api.newscatcherapi.com/news-api(POST /search,POST /articles,GET /stories/{story_id},GET /subscription) - Agent API:
https://api.newscatcherapi.com/agent(POST /runs,GET /runs/{run_id},/monitors,/companies/lists)
Step 2: verify
A wrong key is not refused when you connect. It fails on the first tool call. So verify before anything else:- MCP: call
get_account. It is free and returns the plan, the credit balance and the limits. If it returns an error, fix the key or the sign-in now. - REST:
GET https://api.newscatcherapi.com/news-api/subscriptionwith thex-api-keyheader. It is free and returnscredits_balanceand your plan’s limits.
401. If the person signed in but
their workspace has no API key, every tool returns an error telling them to
create one in the platform.
Rules that break silently
These do not return an error. They return results that look fine and are wrong, empty or narrower than asked. Follow them on every call.- In
search_news,NOTtakes one word or one quoted phrase, and only in upper case.NOT Elon Muskdrops only “Elon” and searches for “Musk”; writeNOT "Elon Musk". A lower-casenotis an ordinary word.NOTchecks the headline, the description and the summary, not the article text, and only the first 10 terms count. list_articlescovers only the last 7 days unless you setfrom. A count of “every article that mentions X” with nofromis a 7-day count. Setfromandto(up to 12 months back). Onsearch_news, the window iswindow(default 7 days, up to 30).- In
search_news, the default window is cut to the plan’s history without a flag. A window you set that is longer than the plan allows is cut and marked as clamped; the default 7 days is cut with no mark. Set the window yourself when the dates matter. - Non-news is handled differently by the two search tools.
search_newsdrops press releases, blogs and opinion by default (setinclude_non_news=trueto keep them).list_articlesincludes them and has no filter to drop them. - Paging stops at 1,000 articles, and a date-only
toends at 00:00.list_articlespages through the first 1,000 matches only;total_hitsstill gives the exact count.to="2026-10-03"means 2026-10-03 00:00, so that day is left out: send2026-10-03T23:59:59. - A company run ends
succeededeven when companies failed. Check the coverage status of every company (news_status). Onlyfoundandno_newsmean the company was searched in full.identity_unknownmeans it was not searched at all.incomplete,out_of_time,model_unavailable,internal_error,failedandnot_searchedmean the search did not finish. - The Agent REST API drops unknown request fields. In
POST /runs, a misspelled field (saylookbackforlookback_days) is ignored without an error, and the run uses the default.lookback_daysabove 365 becomes 365, and0becomes 30. Checkwindow_fromandwindow_toof a company run in the response. - A tool call stops after about 4 minutes and returns what it has. For
agent runs,
get_researchreturns the partial table; call it again until the run’s status issucceeded,failedorcancelled. Do not start the run again.
The tools
The server has four toolsets. All load by default.
To load fewer tools and save context, add
?tools= to the server URL:
https://mcp.newscatcherapi.com/mcp?tools=news or ?tools=news,research.
Unknown names are ignored; if none is valid, every toolset loads.
The server also has two guides you can read as resources:
newscatcher://guides/query-syntax and newscatcher://guides/research-agent.
Credits and limits
One balance of NCC credits pays for everything. Only successful work is charged, and a search that finds nothing is still a success.- Check before big jobs.
start_research(dry_run=true)is free and shows the time, the cost and your balance. Confirmstandardormaxruns, many companies and hourly monitors with the person first. - The full price is held when a run starts. A run your balance cannot
cover is refused with
402. - Check the balance with
get_account(MCP) orGET /subscription(REST), both free. The balance can lag usage by a minute or two. - Your plan limits how many agent runs go at once. One more gets
429 too_many_runs; wait for a run to finish.
When a call fails
401: the key is missing or wrong. Fix it; do not retry.402: not enough credits. Nothing was charged. Tell the person to top up.403: the plan does not allow this (a field, a page depth, a mode, a window older than the plan’s history). Do not retry unchanged.422: the request is invalid; the message names the field. Fix it and retry once.429: wait forRetry-Afterwhen it is sent (for the daily limit it is the next midnight UTC). Fortoo_many_runs, wait for a run to finish.503and500: retry once after a few seconds.- An agent run that ends
failed(model_unavailable,search_failed,worker_restarted,internal_error) is free: start it again.
Examples
News, with MCP: the biggest stories about Nvidia in the last 7 days.dry_run, then call get_research with the run_id
until the status is succeeded.
The same with REST:
202 with a run_id. Poll GET /runs/{run_id} every
15 seconds or so until status is succeeded, failed or cancelled.
Reading these docs
- Docs MCP server:
https://www.newscatcherapi.com/docs/mcpsearches and reads these docs from any MCP client. - Markdown: add
.mdto any page URL to get it as Markdown. - Index:
llms.txtlists every page with a one-line description.

