> SpecStream is the live web data engine for teams and agents. This is the Markdown copy of https://specstream.ai/docs/integrations/litellm-mcp. Every page, with what SpecStream does and costs: https://specstream.ai/llms.txt # LiteLLM MCP Gateway Add SpecStream to the LiteLLM MCP Gateway with one entry under `mcp_servers` in `config.yaml`. Every model and MCP client behind your proxy can then search the live web, read pages and ask for structured data, on your SpecStream account. [SpecStream for LiteLLM MCP GatewayAgent frameworks & builders](https://specstream.ai/integrations/litellm-mcp.md) ## What you need - A LiteLLM proxy you run, with its `config.yaml` and a LiteLLM virtual key to test with. - A SpecStream account. New accounts start with $10 of credit, no card. [Create one](https://specstream.ai/signup?utm_source=litellm-mcp). 1. 1 ## 1. Create a SpecStream API key In SpecStream, open [Agents & API](https://specstream.ai/workspace/agents?tab=keys&utm_source=litellm-mcp), choose **API keys**, then **Create API key**. Give it a total spending limit above 0. Every user of the proxy spends from this key, so the limit is the ceiling for all of them. Put the key in the environment the proxy starts from: Proxy environment ```bash export SPECSTREAM_API_KEY="YOUR_SPECSTREAM_KEY" ``` 2. 2 ## 2. Add SpecStream under mcp\_servers Add this entry to `config.yaml`. SpecStream is a remote server on Streamable HTTP, which LiteLLM calls `http`. `bearer_token` makes LiteLLM send `Authorization: Bearer ` on every request to SpecStream, so `auth_value` holds the key alone, with no `Bearer` in front: config.yaml ```yaml mcp_servers: specstream: url: "https://api.specstream.ai/mcp" transport: "http" description: "Live web search, page reading and structured web data" auth_type: "bearer_token" auth_value: os.environ/SPECSTREAM_API_KEY ``` 3. 3 ## 3. Restart the proxy Start LiteLLM with the file. The name `specstream` meets SEP-986, which LiteLLM asks of every new server, and it becomes the prefix of each SpecStream tool name, as in `specstream-search_web`. Terminal ```bash litellm --config config.yaml ``` 4. 4 ## 4. Check the tools List the tools through the gateway, with your LiteLLM key in `x-litellm-api-key`. The path `/specstream/mcp` scopes the call to SpecStream alone: Terminal ```bash curl -s -X POST http://localhost:4000/specstream/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "x-litellm-api-key: Bearer $LITELLM_API_KEY" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' ``` 5. 5 ## 5. Use it from a model In a request to the proxy's `/v1/responses`, the literal `litellm_proxy/mcp/specstream` points the model at SpecStream. It is a name the proxy reads, not a network address. With `require_approval` set to `never`, LiteLLM runs the tools the model picks and returns the answer: Terminal ```bash curl http://localhost:4000/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $LITELLM_API_KEY" \ -d '{ "model": "YOUR_MODEL", "tools": [ { "type": "mcp", "server_label": "specstream", "server_url": "litellm_proxy/mcp/specstream", "require_approval": "never" } ], "input": "What did the European Central Bank decide at its last meeting? Search the web and cite the pages." }' ``` ## What the check returns A JSON-RPC `result` whose `tools` array holds the SpecStream tools, each name starting with `specstream-`. A `401` means the LiteLLM key is wrong. A `404` means no server is named `specstream`: check the key under `mcp_servers` and restart. If the list comes back empty, read `result._meta`, which holds each server's outcome, and check the SpecStream key in the proxy's environment. ## What the tools do The tools a gateway user reaches most: - `search_web` answers a question from the live web with up to 10 results, each with its URL. It takes `{"q": ""}`. - `read_pages` returns the main text of up to 20 pages or documents (PDF, Word, Excel), read live. It takes `{"urls": [""]}`. - `compile` reads a request for many records into its conditions and the facts to bring back, and `quote_capacity_work` prices it. Both cost nothing. - `authorize_capacity_work` starts the paid run, and only with `confirm_max_cents` equal to the approved maximum. `get_find` follows it and `list_find_rows` reads the rows, each value with its source URL and read time. ## Limit the tools on a shared gateway When no key, team or organization lists MCP servers, LiteLLM opens every server to every key. To give users search and page reading and nothing that starts a paid run, add `allowed_tools` to the entry. LiteLLM blocks every tool the list leaves out: ## Add it in the admin UI or with the API Both store the server in LiteLLM's database, so set `STORE_MODEL_IN_DB=True` in the proxy's environment, or `store_model_in_db: true` under `general_settings`. In the admin UI, open **MCP Servers** and click **Add New MCP Server**. Enter `https://api.specstream.ai/mcp` as the URL, choose **Streamable HTTP** as the transport, choose bearer token authentication and enter the SpecStream key alone as the authentication value. With the management API, set `transport` to `http` yourself. The API takes `sse` when it is left out, and SpecStream serves Streamable HTTP: ## Each user on their own SpecStream key To bill each team on its own SpecStream account, leave `auth_type` and `auth_value` out of the entry. LiteLLM then forwards a header named `x-mcp-{server_alias}-{header_name}` to that one server, so each client sends its own key: `x-mcp-specstream-authorization: Bearer THEIR_SPECSTREAM_KEY` MCP clients such as Cursor or Claude Code connect to `https://YOUR_PROXY/specstream/mcp` with that header beside `x-litellm-api-key`. ## Or sign each user in with OAuth SpecStream also signs people in with OAuth and lets a client register itself. Set `auth_type: "oauth2"` and `oauth2_flow: "authorization_code"` on the entry, with no `client_id` or `client_secret`. LiteLLM finds SpecStream's sign-in, registers itself and asks each user to sign in once. Requests then run on that user's SpecStream account, with its balance and limits. LiteLLM's [MCP OAuth guide (opens in a new tab)](https://docs.litellm.ai/docs/mcp_oauth) covers the redirect address. ## Cost Adding SpecStream to LiteLLM is free. Each `search_web` call is one Search API call at $5 per 1,000 searches of up to 10 results. Each page `read_pages` reads is $0.80 per 1,000 pages, and a page with no text is not charged. Neither needs a quote or an approval: they come out of the key's balance, up to its spending limit. Reading a request and pricing it cost nothing. A Deep Search run charges each delivered row 5¢, 15¢ or $1, depending on how much the row needs, plus 5¢ for a person's email and 15¢ for a phone, never more than the approved maximum. A run that finds nothing costs nothing. [Balance, quotes, and billing](https://specstream.ai/docs/billing.md) has the details. ## Search provider or MCP server LiteLLM also has a search API of its own, `litellm.search`, with providers such as `google_pse` and `searxng`. To keep that call and change only where it searches, follow [the LiteLLM search provider guide](https://specstream.ai/docs/integrations/litellm.md). Use the MCP server when models and MCP clients should call the tools themselves. ## Disconnect Remove the `specstream` entry from `config.yaml` and restart the proxy, or delete the server under **MCP Servers** in the admin UI. To end its access on the SpecStream side, revoke the key under **Agents & API**. Your saved results stay in your workspace. Questions go to [support@specstream.ai](mailto:support@specstream.ai). ## More [SpecStream for LiteLLM MCP Gateway](https://specstream.ai/integrations/litellm-mcp.md) covers what it does in LiteLLM MCP Gateway 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).