GPT Researcher MCP retriever

Add SpecStream to mcp_configs and set RETRIEVER=mcp, and GPT Researcher's MCP retriever searches the live web and reads whole pages through one server and one key, SPECSTREAM_API_KEY.

SpecStream for GPT Researcher MCP retrieverAgent frameworks & builders

What you need

GPT Researcher. pip install gpt-researcher includes the MCP parts.
Python 3.12 or newer for SpecStream's local MCP command.
A SpecStream account. New accounts start with $10 of credit, no card. Create one.

1
1. Create a SpecStream API key
In SpecStream, open Agents & API, choose API keys, then Create API key, and give it a spending limit above 0. Export it in the shell GPT Researcher runs in, or put it in the same .env file as your model key:
Shell
export SPECSTREAM_API_KEY="YOUR_SPECSTREAM_KEY"
2
2. Install the local MCP command
GPT Researcher starts a local MCP server from a command. specstream-mcp-stdio is that command: it reads SPECSTREAM_API_KEY and passes each tool call to https://api.specstream.ai/mcp. The package has no dependencies.
Shell
pip install specstream-mcp-stdio

3. Add SpecStream to mcp_configs

Set RETRIEVER to mcp before you create the researcher, and pass one entry in mcp_configs. These are the fields GPT Researcher reads for a local server: name, command, args and env.

research.py
import asyncio
import os

from gpt_researcher import GPTResearcher

os.environ["RETRIEVER"] = "mcp"


async def main():
    researcher = GPTResearcher(
        query="Which EU countries changed their heat pump subsidies in 2026, and by how much?",
        mcp_configs=[
            {
                "name": "specstream",
                "command": "specstream-mcp-stdio",
                "args": [],
                "env": {"SPECSTREAM_API_KEY": os.environ["SPECSTREAM_API_KEY"]},
            }
        ],
    )
    await researcher.conduct_research()
    report = await researcher.write_report()
    print(report)


asyncio.run(main())

4
4. Run it
Run the file. GPT Researcher loads SpecStream's tools, picks the ones that fit the query, calls them, and writes the report from what they return. To see each tool call, set the log level to debug with logging.basicConfig(level=logging.DEBUG) at the top of the file.
Shell
python research.py

Which tools the retriever calls

GPT Researcher does not call every tool a server offers. For each query its model reads the tool list and keeps at most 3. For a research question those are the two below in most runs, and both run with no quote.

search_web answers a question from the live web with up to 10 results, each with its URL. It takes {"q": "<the question>"}.
read_pages returns the main text of up to 20 pages or documents (PDF, Word, Excel), read live. It takes {"urls": ["<url>"]}.

Keep your web retriever beside it

RETRIEVER takes a list. RETRIEVER=tavily,mcp keeps Tavily for the sub queries and adds the MCP stage, the pairing GPT Researcher's README shows. To run both stages on SpecStream, use RETRIEVER=searx,mcp and set SEARX_URL as in the retriever guide. Then one key pays for every search in the run.

How often the MCP stage runs

MCP_STRATEGY sets it. The default is fast.

MCP_STRATEGY	What GPT Researcher does	What it means for cost
`fast`	Runs the MCP stage once, with the main query	A few tool calls a report
`deep`	Runs the MCP stage for every sub query	A few tool calls for each sub query
`disabled`	Skips MCP	No SpecStream call from the MCP stage

Why a local command and not the address

SpecStream's MCP server is remote, at https://api.specstream.ai/mcp, and it needs your key on every request. GPT Researcher does accept a connection_url, but its client code today hands connection_token on as a field named token and builds no Authorization header from it. So a remote entry would reach SpecStream with no key. The local command sends the key for you.

A cited report from SpecStream itself

The same server holds SpecStream's research reports: research_price, start_research and get_research. A report answers a question with written text and [1] markers, and each cited sentence names the page it was read on. It costs $0.10 (quick), $0.30 (standard) or $1.00 (deep), charged once, when the report is delivered.

start_research starts only with confirm_max_cents equal to a price a person approved, and a GPT Researcher run has nobody to ask. So inside a run, let the retriever search and read. When you want SpecStream to write the whole report, call POST /v1/research from your own code. Research reports has the request and the reply.

Cost

Each search_web call is one Search API search at $5 per 1,000 searches of up to 10 results, and each page read_pages reads is $0.80 per 1,000 pages. A page with no text is not charged. Both come out of your balance with no quote, up to the key's spending limit. With RETRIEVER=searx,mcp, the searches that go through SEARX_URL run the fast search at $1 per 1,000. New accounts start with $10 of credit, no card. See how billing works.

If the command is not found

GPT Researcher runs on Python 3.11 or newer and the SpecStream command needs 3.12. If your GPT Researcher environment is on 3.11, install specstream-mcp-stdio with a 3.12 interpreter and put the full path of the command in command. The same fix applies when the command is not on the PATH GPT Researcher starts from. If no tool loads, check that SPECSTREAM_API_KEY is set in the shell you run from.

Disconnect

Remove the specstream entry from mcp_configs and set RETRIEVER back to the retriever you used before. Revoke the key under Agents & API in SpecStream. Questions go to [email protected].

SpecStream for GPT Researcher MCP retriever covers what it does in GPT Researcher MCP retriever on one page. Every other tool has its guide in Connect your tools. You see the most a request can cost before it starts, and the matches are paid from your balance. Billing has the details. For help, email [email protected].