Skip to the page

Use SpecStream from the OpenAI Responses and Agents APIs

The Responses API can call a remote MCP server as a tool. Point it at SpecStream and your own code gets lists of matches only, with the page behind each fact.

What you need

  • A SpecStream API key. Create one in the workspace under Agents & API, with a spending limit that fits the job. See the API page.
  • An OpenAI API key and a model that supports remote MCP tools.

Add SpecStream as a tool

Set server_url to the SpecStream address and pass your SpecStream key in authorization. The Responses API doesn't store that value, so send it with every request. Keep it in an environment variable or a secret store, never in a prompt.

Python
import os


from openai import OpenAI


client = OpenAI()


response = client.responses.create(
    model="gpt-6-astra",
    tools=[
        {
            "type": "mcp",
            "server_label": "specstream",
            "server_description": "Find lists on the live web, checked against every condition, with sources.",
            "server_url": "https://api.specstream.ai/mcp",
            "authorization": os.environ["SPECSTREAM_API_KEY"],
            "allowed_tools": [
                "compile",
                "edit_spec",
                "quote_capacity_work",
                "authorize_capacity_work",
                "get_find",
                "list_find_rows",
                "export_find",
                "cancel_find",
                "get_capacity_balance",
                "list_projects",
                "get_project",
                "list_request_templates",
            ],
            "require_approval": {
                "never": {
                    "tool_names": [
                        "compile",
                        "edit_spec",
                        "quote_capacity_work",
                        "get_find",
                        "list_find_rows",
                        "get_capacity_balance",
                        "list_projects",
                        "get_project",
                        "list_request_templates",
                    ]
                }
            },
        }
    ],
    input="Find open SAM.gov tenders for translation services with a deadline after November 1. Include the buyer and the estimated value.",
)
print(response.output_text)

The same tool as a plain request:

Terminal
curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-astra",
    "tools": [{
      "type": "mcp",
      "server_label": "specstream",
      "server_url": "https://api.specstream.ai/mcp",
      "authorization": "'"$SPECSTREAM_API_KEY"'",
      "allowed_tools": ["compile", "quote_capacity_work", "authorize_capacity_work", "get_find", "list_find_rows"],
      "require_approval": "always"
    }],
    "input": "Find datasets on urban tree canopy published since 2020 under an open license."
  }'

Choose the tools the model can see

allowed_tools limits the model to the request-to-results path: understand a request (compile, edit_spec), get a quote (quote_capacity_work), start approved work (authorize_capacity_work), follow it (get_find), and read or download results (list_find_rows, export_find). Leave out the tools your job doesn't need and the model has less to choose from.

Approve paid work yourself

Nothing new runs until someone approves a quote. The example lets the model read and prepare without asking, and keeps the default approval step for authorize_capacity_work and the other tools that start work or change something. When the model wants to approve a quote, the response carries an mcp_approval_request with the quote ID, the maximum and the request key. Show them to a person or check them in code, then answer:

Python
approval_request = next(item for item in response.output if item.type == "mcp_approval_request")


follow_up = client.responses.create(
    model="gpt-6-astra",
    previous_response_id=response.id,
    tools=response.tools,
    input=[
        {
            "type": "mcp_approval_response",
            "approval_request_id": approval_request.id,
            "approve": True,
        }
    ],
)

The approved maximum is also a hard ceiling in SpecStream: work stops at it, and your API key's own spending limit applies on top. Read how quotes and billing work before you automate approvals.

Follow a run and read the results

Ask the model to check the run with get_find until it finishes, then read rows with list_find_rows, following next_cursor until it is empty. Each row comes with the source behind each check. The separate possible list holds candidates SpecStream couldn't fully check; they are not results.

Agents

Anything built on OpenAI's agent tooling that accepts a remote MCP server takes the same address and key. The tools, approvals and limits above work the same way.

Using ChatGPT or Codex instead of the API? Add SpecStream to ChatGPT. Other clients are on the setup guides, and the full tool list is on the MCP page.