> SpecStream is the live web data engine for teams and agents. This is the Markdown copy of https://specstream.ai/docs/integrations/gpt-researcher-mcp. Every page, with what SpecStream does and costs: https://specstream.ai/llms.txt

# 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](https://specstream.ai/integrations/gpt-researcher-mcp.md)

## 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](https://specstream.ai/signup?utm_source=gpt-researcher-mcp).

1.  1

    ## 1. Create a SpecStream API key

    In SpecStream, open [Agents & API](https://specstream.ai/workspace/agents?tab=keys&utm_source=gpt-researcher-mcp), 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

    ```bash
    export SPECSTREAM_API_KEY="YOUR_SPECSTREAM_KEY"
    ```

2.  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

    ```bash
    pip install specstream-mcp-stdio
    ```

3.  3

    ## 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

    ```python
    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

    ## 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

    ```bash
    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](https://specstream.ai/docs/integrations/gpt-researcher.md). 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](https://specstream.ai/docs/research.md) 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](https://specstream.ai/docs/billing.md).

## 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 [support@specstream.ai](mailto:support@specstream.ai).

## More

[SpecStream for GPT Researcher MCP retriever](https://specstream.ai/integrations/gpt-researcher-mcp.md) covers what it does in GPT Researcher MCP retriever on one page. Every other tool has its guide in [Connect your tools](https://specstream.ai/docs/integrations.md). You see the most a request can cost before it starts, and the matches are paid from your balance. [Billing](https://specstream.ai/docs/billing.md) has the details. For help, email [support@specstream.ai](mailto:support@specstream.ai).