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

# Codewhale

Add SpecStream to Codewhale's ~/.codewhale/mcp.json, sign in once and run /mcp reload. The coding agent can then ask for live web data mid-task, and you see the price before anything runs.

[SpecStream for CodewhaleCoding agents](https://specstream.ai/integrations/codewhale.md)

## What you need

-   Codewhale v0.10.2 or newer, running in a terminal.
-   A SpecStream account. New accounts start with $10 of credit, no card. [Create one](https://specstream.ai/signup?utm_source=codewhale).

1.  1

    ## 1. Add SpecStream to mcp.json

    Codewhale reads its MCP servers from `~/.codewhale/mcp.json`. If the file does not exist, run `codewhale mcp init` first. Add a `specstream` entry under `servers`. An entry with only a `url` is a remote server over Streamable HTTP, which is what SpecStream serves at `https://api.specstream.ai/mcp`.

    If your file uses `mcpServers` instead of `servers`, put the entry there. Codewhale reads either key, but a file that holds both fails to parse.

    ~/.codewhale/mcp.json

    ```json
    {
      "servers": {
        "specstream": {
          "url": "https://api.specstream.ai/mcp"
        }
      }
    }
    ```

2.  2

    ## 2. Or add it from the command line

    The same entry, written for you:

    Terminal

    ```bash
    codewhale mcp add specstream --url "https://api.specstream.ai/mcp"
    ```

3.  3

    ## 3. Sign in to SpecStream

    Run the login command. Codewhale finds SpecStream's sign-in, opens it in your browser and waits on a local callback. Sign in and approve the access. Codewhale keeps the token in its secrets store and refreshes it, so there is no key in the file.

    Terminal

    ```bash
    codewhale mcp login specstream
    ```

4.  4

    ## 4. Run /mcp reload

    In a running Codewhale session, type `/mcp reload`. It rebuilds the live tool pool from the file, with no restart. `/mcp` then lists SpecStream with its tools, named `mcp_specstream_<tool>`, for example `mcp_specstream_compile`.

5.  5

    ## 5. Ask Codewhale

    Describe the data you need and the details to bring back. For example:

    In a Codewhale session

    ```text
    Find open-source Rust crates for parsing PDFs, with each one's repository, license and the date of its latest release. Use SpecStream.
    ```

## Use an API key instead of sign-in

On a machine with no browser, create a key: open **Agents & API** in your SpecStream workspace, go to **API keys** and select **Create API key**, with a spending limit. Export it as `SPECSTREAM_API_KEY` in the shell that starts Codewhale, and name the variable in the entry with `bearer_token_env_var`. Codewhale then sends `Authorization: Bearer` with its value, and the key stays out of the file. A literal `headers` value does not expand `${SPECSTREAM_API_KEY}`, so use the variable name as shown.

## Approvals

Codewhale asks before it runs an MCP tool that changes something. Keep `authorize_capacity_work` out of the entry's `always_allow_tools`, so a paid run waits for your yes in Codewhale too. SpecStream adds its own gate: nothing paid starts until you approve the maximum it quotes.

## What Codewhale calls

A request for a list moves through these tools in order. For one quick answer or the text of known pages there are two direct tools.

-   `compile` reads the request and says what SpecStream will look for.
-   `quote_capacity_work` prices it. It spends nothing.
-   `authorize_capacity_work` starts the work after you approve the maximum.
-   `get_find` follows progress, and `list_find_rows` reads the rows, each value with its source.
-   `search_web` answers one question at $5 per 1,000 searches, and `read_pages` returns the text of pages you name at $0.80 per 1,000 pages.

## One project only

To use SpecStream in one repository, put the same entry in `<workspace>/.codewhale/mcp.json`. Codewhale reads it once you trust the workspace, and a project entry overrides a global one with the same name.

## If the tools do not show

Run `codewhale doctor` to see which MCP file Codewhale resolved. In the session, `/mcp validate` shows each server's last state without reconnecting, and `/mcp reload` connects again. A 401 means the sign-in is missing or expired: run `codewhale mcp login specstream`, then `/mcp reload`.

## Cost

Connecting SpecStream to Codewhale is free, and so are reading a request and pricing it. Each matching row costs 5¢, 15¢ or $1, depending on what the row needs, plus 5¢ for a person's email and 15¢ for a phone. A run can't cost more than the maximum you approved, and a run that finds nothing costs nothing. [Balance, quotes and billing](https://specstream.ai/docs/billing.md) has the details.

## Disconnect

Run `codewhale mcp remove specstream`, or delete the entry and run `/mcp reload`. `codewhale mcp logout specstream` clears the token Codewhale stored. To end the access on SpecStream's side, open **Agents & API** in your workspace and revoke Codewhale under **OAuth applications**, or the key under **API keys**. Your saved results stay in your workspace. Questions go to [support@specstream.ai](mailto:support@specstream.ai).

## More

[SpecStream for Codewhale](https://specstream.ai/integrations/codewhale.md) covers what it does in Codewhale 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).