Skip to the page
Get started free

CUGA

Add SpecStream to CUGA's tool registry with one entry in its MCP servers YAML, and IBM's agent can search the live web, read whole pages and build lists of records inside its web and API tasks.

SpecStream for CUGAAgent frameworks & builders

What you need

  • CUGA from its repository, with Python 3.12 and uv.
  • A SpecStream account and an API key. New accounts get $10 of credit, no card.

  1. 1. Create a SpecStream API key

    CUGA's registry sends a bearer token to a remote MCP server, so SpecStream's key goes in one. In your SpecStream workspace, open Agents & API, choose API keys, then Create API key, and set a total spending limit. Then set it in the shell that starts CUGA:

    Terminal
    export SPECSTREAM_API_KEY=YOUR_SPECSTREAM_API_KEY

  2. 2. Add SpecStream to the registry YAML

    The registry reads config/mcp_servers.yaml in its package by default, or the file that MCP_SERVERS_FILE names. Add the specstream entry under mcpServers in a file of your own, for example my_tools.yaml, and copy in any services you keep from the default file.

    transport: http is Streamable HTTP. The registry turns auth with type: bearer into an Authorization: Bearer header, and env://SPECSTREAM_API_KEY reads the key from the environment, so it never sits in the file.

    my_tools.yaml
    mcpServers:
      specstream:
        url: https://api.specstream.ai/mcp
        transport: http
        description: Live web search, page reading and lists of records from the live web
        auth:
          type: bearer
          value: env://SPECSTREAM_API_KEY

  3. 3. Start the registry and check SpecStream

    Start the registry with your file. It listens on http://127.0.0.1:8001, logs Creating HTTP transport for specstream and then the tools it retrieved from SpecStream. GET /applications on that address lists SpecStream beside your other apps.

    Terminal
    MCP_SERVERS_FILE=./my_tools.yaml uv run python -m cuga.backend.tools_env.registry.registry.api_registry_server

  4. 4. Run CUGA with the same file

    Export the same file and start the demo. cuga start demo keeps an MCP_SERVERS_FILE you exported. A saved agent uses only the registry apps its tools list names, so add specstream there if your agent has one.

    Terminal
    export MCP_SERVERS_FILE=./my_tools.yaml
    uv run cuga start demo

  5. 5. Ask CUGA

    Give CUGA a task that needs the live web and name SpecStream:

    In a CUGA chat
    Use SpecStream to find the current stable release of Node.js and summarize its release notes.

What CUGA gets

The registry names each MCP tool after its server, so SpecStream's tools reach CUGA as specstream_search_web, specstream_read_pages and so on.

  • search_web answers a question from the live web, with up to 10 results for $5 per 1,000 searches. A search that returns nothing costs nothing.
  • read_pages returns the main text of up to 20 pages or documents (PDF, Word, Excel) in one call, at $0.80 per 1,000 pages. A page that gives no text is not charged.
  • Deep Search builds a list from a request in plain words. compile reads the request, quote_capacity_work prices it for free, and authorize_capacity_work starts it only with the maximum you approved. get_find and list_find_rows read the rows, each with its source.

Choose the tools with include

include limits a server to the tools you list. For a CUGA agent that runs on its own, give it search and page reading only, and keep Deep Search for runs where a person approves the quote:

  • include: [search_web, read_pages] under the specstream entry.

Spending

Searches and page reads are charged per call from your balance, with no quote. The key's total spending limit caps what every run on it can spend. Deep Search adds its own gate: nothing paid starts until the maximum of its quote is approved.

If the registry can't reach SpecStream

Check that SPECSTREAM_API_KEY is set in the shell that starts the registry: with no value, the registry sends no Authorization header and SpecStream refuses the call. Keep transport: http; without it the registry picks SSE for any address that holds /sse and HTTP for the rest. It waits 15 seconds for a server's tool list.

Search quality

SpecStream's Search API scores 97.9 F-score on all 1,000 SimpleQA Verified questions and 64.0 item F1 on all 200 WideSearch tasks. The method is on benchmarks.

Cost

Connecting SpecStream to CUGA is free, and new accounts start with $10 of credit. A search of up to 10 results costs $5 per 1,000, and a page read costs $0.80 per 1,000. Deep Search is priced per delivered row and quoted before it runs, and a run can't cost more than the maximum approved. See pricing and how billing works.

Remove it

Delete the specstream entry from your YAML and restart the registry. Revoke the key under Agents & API in your SpecStream workspace. Questions: [email protected].

More

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