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

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.

1
1. Create a SpecStream API key
In SpecStream, open Agents & API, 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
export SPECSTREAM_API_KEY="YOUR_SPECSTREAM_KEY"

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 <key> on every request to SpecStream, so auth_value holds the key alone, with no Bearer in front:

config.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. 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
litellm --config config.yaml

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
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. 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
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": "<the question>"}.
read_pages returns the main text of up to 20 pages or documents (PDF, Word, Excel), read live. It takes {"urls": ["<url>"]}.
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) 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 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. 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 [email protected].

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