> SpecStream is the live web data engine for teams and agents. This is the Markdown copy of https://specstream.ai/docs/integrations/cuga. Every page, with what SpecStream does and costs: https://specstream.ai/llms.txt # 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](https://specstream.ai/integrations/cuga.md) ## 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 ## 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 ```bash export SPECSTREAM_API_KEY=YOUR_SPECSTREAM_API_KEY ``` 2. 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 ```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 ## 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 ```bash MCP_SERVERS_FILE=./my_tools.yaml uv run python -m cuga.backend.tools_env.registry.registry.api_registry_server ``` 4. 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 ```bash export MCP_SERVERS_FILE=./my_tools.yaml uv run cuga start demo ``` 5. 5 ## 5. Ask CUGA Give CUGA a task that needs the live web and name SpecStream: In a CUGA chat ```text 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](https://specstream.ai/benchmarks.md). ## 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](https://specstream.ai/pricing.md) and [how billing works](https://specstream.ai/docs/billing.md). ## Remove it Delete the `specstream` entry from your YAML and restart the registry. Revoke the key under **Agents & API** in your SpecStream workspace. Questions: [support@specstream.ai](mailto:support@specstream.ai). ## More [SpecStream for CUGA](https://specstream.ai/integrations/cuga.md) covers what it does in CUGA 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).