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

# ContextForge

Register SpecStream with your ContextForge gateway through `POST /gateways`, and every client behind it can search the live web, read pages and ask for structured data through one ContextForge endpoint, on one SpecStream key with a spending limit.

[SpecStream for ContextForgeAgent frameworks & builders](https://specstream.ai/integrations/contextforge.md)

## What you need

-   A running ContextForge gateway, from PyPI (`mcp-contextforge-gateway`) or the container, and a gateway token made with `mcpgateway.utils.create_jwt_token` in `MCPGATEWAY_BEARER_TOKEN`, as its README shows. `curl` and `jq`.
-   A SpecStream account. New accounts start with $10 of credit, no card. [Create one](https://specstream.ai/signup?utm_source=contextforge).

1.  1

    ## 1. Create a SpecStream API key

    In SpecStream, open [Agents & API](https://specstream.ai/workspace/agents?tab=keys&utm_source=contextforge), choose **API keys**, then **Create API key**, and give it a spending limit above 0.

    ContextForge keeps one token per gateway and sends it on every call it forwards to SpecStream, so every user of these tools spends from this key and its limit is the ceiling for all of them. Make a key for the gateway alone, and put it in `SPECSTREAM_API_KEY` in your shell.

2.  2

    ## 2. Register SpecStream with POST /gateways

    Send the name, SpecStream's address and the transport. The transport defaults to `SSE`, so set `STREAMABLEHTTP`. `auth_type` `bearer` with the key in `auth_token` makes ContextForge send `Authorization: Bearer <key>` to SpecStream. Use your gateway's address in place of `http://localhost:4444` (port 8080 behind the Docker Compose stack's nginx):

    Terminal

    ```bash
    GATEWAY_ID=$(curl -s -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "specstream",
        "url": "https://api.specstream.ai/mcp",
        "description": "Live web search, page reading and Deep Search",
        "transport": "STREAMABLEHTTP",
        "auth_type": "bearer",
        "auth_token": "'"$SPECSTREAM_API_KEY"'"
      }' \
      http://localhost:4444/gateways | jq -r '.id')
    echo "$GATEWAY_ID"
    ```

3.  3

    ## 3. Check the tools

    ContextForge reads SpecStream's tool list when it registers the gateway. Each tool's name starts with the gateway's slug and the separator, `-` by default, so `search_web` becomes `specstream-search-web`. List the tools of this gateway alone:

    Terminal

    ```bash
    curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
      "http://localhost:4444/tools?gateway_id=$GATEWAY_ID&limit=0" | jq -r '.[] | "\(.id) \(.name)"'
    ```

4.  4

    ## 4. Bundle the tools in a virtual server

    Clients reach tools through a virtual server. This one carries web search and page reading only; add the ids of the Deep Search tools, such as `specstream-compile` and `specstream-quote-capacity-work`, if your clients should ask for structured data too:

    Terminal

    ```bash
    TOOL_IDS=$(curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
      "http://localhost:4444/tools?gateway_id=$GATEWAY_ID&limit=0" \
      | jq -c '[.[] | select(.name == "specstream-search-web" or .name == "specstream-read-pages") | .id]')
    
    curl -s -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"server": {"name": "web", "description": "Live web search and page reading", "associated_tools": '"$TOOL_IDS"'}}' \
      http://localhost:4444/servers | jq -r '.id'
    ```

5.  5

    ## 5. Connect a client

    Point any MCP client at `http://localhost:4444/servers/<server id>/mcp` over Streamable HTTP, with a ContextForge token in the `Authorization` header. The client sees `specstream-search-web` and `specstream-read-pages` next to the other tools you bundled.

## Or add it in the Admin UI

Open `/admin`, go to **MCP Servers**, and fill in **Add New MCP Server or Gateway**: **MCP Server Name** `specstream`, **MCP Server URL** `https://api.specstream.ai/mcp`, **Transport Type** **Streamable HTTP**, **Authentication Type** **Bearer Token**, and the SpecStream key in **Token**. Click **Add Gateway**. ContextForge imports the tools the same way.

## When registration is asynchronous

With `GATEWAY_ASYNC_LIFECYCLE_ENABLED=true`, `POST /gateways` answers `202 Accepted` with `status` `pending`, and a worker connects to SpecStream after the reply. Read `GET /gateways/specstream` until the gateway is `active`, then list its tools. After SpecStream adds a tool, `POST /gateways/$GATEWAY_ID/tools/refresh` reads the list again.

## Ask through the gateway

In a client, ask a question with a recent answer. The model calls `specstream-search-web` with `{"q": "<the question>"}` and gets back an `answer` and the `sources` it read, each with `url`, `title`, `site` and `snippet`. To read a page it found, it calls `specstream-read-pages` with `{"urls": ["<url>"]}` and gets the page's main text as Markdown.

## Who can spend from the key

A gateway registered with no `visibility` is `public`. Set `"visibility": "team"` with your `team_id`, or `"private"`, in the registration body when only some users of the gateway should reach SpecStream's tools. A virtual server with only the search and reading tools keeps Deep Search out of their reach as well.

## Why SpecStream behind a gateway

SpecStream's Search API reads each answer from the live web at the moment of the call. It scores 97.9 F-score on all 1,000 SimpleQA Verified questions and 64.0 item F1 on all 200 WideSearch tasks. Scores and method are on the [benchmarks page](https://specstream.ai/benchmarks.md).

One registration gives every client search, page reading and structured records with a source URL and read time on every value, on one key and one spending limit.

## Cost

Registering SpecStream in ContextForge is free. Each `specstream-search-web` call is one Search API call at $5 per 1,000 searches of up to 10 results, and each page `specstream-read-pages` reads is $0.80 per 1,000 pages; a page with no text is not charged. Both come out of the balance with no quote and no approval, within the key's spending limit.

Deep Search is priced per row, and nothing runs until its quote is approved: `authorize_capacity_work` needs the approved maximum in `confirm_max_cents`, and a run cannot cost more. [Search API](https://specstream.ai/search-api.md), [Extract API](https://specstream.ai/extract-api.md) and [billing](https://specstream.ai/docs/billing.md).

## Remove

`DELETE /gateways/$GATEWAY_ID` removes SpecStream and its tools from ContextForge, and `POST /gateways/$GATEWAY_ID/state?activate=false` turns it off and keeps it. Revoke the key in SpecStream's **Agents & API** to end its access at once. Every tool is described in the [MCP guide](https://specstream.ai/docs/mcp.md). Questions go to [support@specstream.ai](mailto:support@specstream.ai).

## More

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