> SpecStream is the live web data engine for teams and agents. This is the Markdown copy of https://specstream.ai/docs/integrations/optillm. Every page, with what SpecStream does and costs: https://specstream.ai/llms.txt # OptiLLM Add SpecStream to OptiLLM's MCP plugin with one entry in mcp\_config.json, and any model behind the proxy can search the live web and read pages, with no Chrome on the server. [SpecStream for OptiLLMAgent frameworks & builders](https://specstream.ai/integrations/optillm.md) ## What you need - OptiLLM 0.4 or newer (`pip install optillm`), started with the key of the model provider it proxies, and a model that supports tool calls. - A SpecStream API key. New accounts start with $10 of credit, no card. [Create an account](https://specstream.ai/signup?utm_source=optillm). 1. 1 ## 1. Create a SpecStream API key OptiLLM's MCP plugin connects with a header and has no browser sign-in, so it uses an API key. In SpecStream, open [Agents & API](https://specstream.ai/workspace/agents?tab=keys&utm_source=optillm), choose **API keys**, then **Create API key**. Give it execute permission and a spending limit above zero, so it can search and read pages. Copy the key when it is shown. It is not shown again. 2. 2 ## 2. Put the header value in one environment variable The plugin replaces a header value with an environment variable only when the whole value is `${NAME}`. A value written as `Bearer ${NAME}` is sent as it is written, and SpecStream answers `401`. So keep the whole header value, `Bearer` and the key, in one variable, and set it in the shell that starts OptiLLM: Shell ```bash export SPECSTREAM_AUTH="Bearer YOUR_SPECSTREAM_API_KEY" ``` 3. 3 ## 3. Add SpecStream to mcp\_config.json Open `~/.optillm/mcp_config.json` and add an entry under `mcpServers`. SpecStream is a remote server on Streamable HTTP, so `transport` is `streamable_http` (the plugin also accepts `streamable-http` and `http`). The `description` goes to the model with the tool list. `timeout` is the connection timeout in seconds, 5 by default: ~/.optillm/mcp\_config.json ```json { "mcpServers": { "specstream": { "transport": "streamable_http", "url": "https://api.specstream.ai/mcp", "headers": { "Authorization": "${SPECSTREAM_AUTH}" }, "timeout": 30, "description": "Live web search and page reading" } }, "log_level": "INFO" } ``` 4. 4 ## 4. Start OptiLLM Start the proxy in the same shell, so it has `SPECSTREAM_AUTH`. The plugin reads `mcp_config.json` again on every request, so a later change to the file needs no restart. A new or changed environment variable does. Shell ```bash optillm ``` 5. 5 ## 5. Call the mcp plugin Put `mcp-` before the model name, or send `"optillm_approach": "mcp"` in `extra_body`. Ask something that needs the web: Python ```python from openai import OpenAI client = OpenAI(base_url="http://localhost:8000/v1") response = client.chat.completions.create( model="mcp-gpt-4o-mini", messages=[{"role": "user", "content": "Search the web: what changed in the latest Python release? Name the pages you used."}], ) print(response.choices[0].message.content) ``` ## What the model gets The plugin shows SpecStream's tools to the model as `specstream.`. Two of them do the work in one request: - `specstream.search_web` with `q`: one Search API call. It returns the answer with the page it was read from, and the ranked results with title, URL and snippet. The Search API is the most accurate web search API on SimpleQA Verified and WideSearch ([scores and method](https://specstream.ai/benchmarks.md)). - `specstream.read_pages` with `urls`: one Extract API call that returns the main text of up to 20 pages, PDF, Word and Excel files included. A page that refuses a plain read is tried again as a browser would ask for it, then in a real browser, then from the site's own feed, then from its newest public archive capture. ## One round of tool calls per request OptiLLM's plugin runs the tool calls the model asks for once, sends the results back, and returns the model's next reply. A search, or a read of pages you name, fits in that round. Lists with a price to approve (Deep Search) take several calls and your approval, so ask for those from an assistant connected to the [SpecStream MCP server](https://specstream.ai/docs/mcp.md). ## Next to the web\_search and readurls plugins OptiLLM's own `web_search` plugin runs Google searches by driving Chrome with Selenium, so the host needs Chrome. Its `readurls` plugin fetches the URLs written in the request. Through the `mcp` plugin, SpecStream answers both over HTTPS with no browser on the OptiLLM host, and the model decides when to search and which pages to read. ## If the model answers without searching When the plugin cannot reach any server, it answers without tools and writes the reason to `~/.optillm/logs/mcp_plugin.log`. The line `Environment variable SPECSTREAM_AUTH not found for header Authorization` means OptiLLM started without the variable: set it and start OptiLLM again. A `401` means the header reached SpecStream without a valid key: check that the variable holds `Bearer`, a space and the key. ## Cost Each `search_web` call is one Search API call at $5 per 1,000 searches of up to 10 results. Each page `read_pages` returns with text costs $0.80 per 1,000 pages, and a page with no text is not charged. Both come out of your balance with no quote and no approval, and the key's spending limit caps what it can spend. New accounts start with $10 of credit, no card. [Balance and billing](https://specstream.ai/docs/billing.md) has the details. ## Disconnect Remove the `specstream` entry from `mcp_config.json`. Then open **Agents & API** in your workspace, choose **API keys**, and revoke the key. Questions go to [support@specstream.ai](mailto:support@specstream.ai). ## More [SpecStream for OptiLLM](https://specstream.ai/integrations/optillm.md) covers what it does in OptiLLM 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).