Skip to the page
Get started free

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

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.

  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
    {
      "servers": {
        "specstream": {
          "url": "https://api.specstream.ai/mcp"
        }
      }
    }

  2. 2. Or add it from the command line

    The same entry, written for you:

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

  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
    codewhale mcp login specstream

  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. Ask Codewhale

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

    In a Codewhale session
    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 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 [email protected].

More

SpecStream for Codewhale covers what it does in Codewhale 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].