OpenAI Agents SDK MCP: hosted vs Streamable HTTP

Setup, step by step

1. Step 1

   Create an agent key

   In the Locus Pro dashboard, open Connect, then API keys, then An agent. Pick the tools the agent may call, a credit cap per call and an expiry. Store the lcac_ key in your secret manager next to your OpenAI key.

   export LOCUS_AGENT_CONNECTION="lcac_..."   # agent key, from your secret store
   export LOCUS_MCP_URL="https://api.paywithlocus.com/api/credits/mcp"

2. Step 2

   Install the Agents SDK

   The Python package is openai-agents. The TypeScript package is @openai/agents, which uses Zod v4 for tool schemas. Both read OPENAI_API_KEY.

   pip install openai-agents
   
   # TypeScript
   npm install @openai/agents zod

3. Step 3

   Connect from your process (Python)

   MCPServerStreamableHttp sends the key in an Authorization header, which works with both major versions of the mcp package. Raise client_session_timeout_seconds from its 5-second default, because a paid scrape or enrichment can take longer.

   import asyncio
   import os
   from agents import Agent, Runner
   from agents.mcp import MCPServerStreamableHttp
   
   async def main() -> None:
       async with MCPServerStreamableHttp(
           name="locus_pro",
           params={
               "url": os.environ["LOCUS_MCP_URL"],
               "headers": {"Authorization": f"Bearer {os.environ['LOCUS_AGENT_CONNECTION']}"},
               "timeout": 60,
           },
           cache_tools_list=True,
           client_session_timeout_seconds=60,
       ) as server:
           agent = Agent(
               name="Researcher",
               instructions="Use the Locus tools. Always pass max_credits to execute.",
               mcp_servers=[server],
           )
           result = await Runner.run(agent, "Use firecrawl/search for MCP gateway pricing. Pass max_credits 5.")
           print(result.final_output)
   
   asyncio.run(main())

4. Step 4

   Or let OpenAI call Locus (TypeScript hosted tool)

   hostedMcpTool hands the connection to the Responses API. Its authorization field takes the raw lcac_ key, without the word Bearer. requireApproval defaults to 'never'.

   import { Agent, run, hostedMcpTool } from '@openai/agents';
   
   const agent = new Agent({
     name: 'Researcher',
     instructions: 'Use the Locus tools. Always pass max_credits to execute.',
     tools: [
       hostedMcpTool({
         serverLabel: 'locus_pro',
         serverUrl: 'https://api.paywithlocus.com/api/credits/mcp',
         authorization: process.env.LOCUS_AGENT_CONNECTION!,
         requireApproval: 'never',
       }),
     ],
   });
   
   const result = await run(agent, 'Use firecrawl/search for MCP gateway pricing. Pass max_credits 5.');
   console.log(result.finalOutput);

5. Step 5

   Confirm the charge

   The execute result reports credits_charged and credits_balance. Ask the agent for both, or call get_balance afterwards, which is free.

   What did that call cost, and what is my Locus balance now?

Hosted MCP tool or Streamable HTTP server: which should I use?

Use MCPServerStreamableHttp unless you have a reason to hand the connection to OpenAI. It keeps the key in your runtime, works with any model the SDK runs, and supports guardrails on each tool call.

The hosted tool saves a network hop through your code and suits OpenAI Responses models. Your Locus key is sent to OpenAI, and client-side tool guardrails do not apply to hosted calls.

Which credential and header does the Agents SDK need?

An agent key in every case. Agents built with the SDK run unattended, and browser OAuth is for interactive clients. Never give the agent the lcr_ secret key.

The header format changes by path. MCPServerStreamableHttp takes a normal header: Authorization: Bearer lcac_.... The hosted tool takes the raw lcac_ key in authorization. The separate managed Agents API expects the full Bearer value in its MCP transport authorization field.

Why do paid calls time out after 5 seconds?

client_session_timeout_seconds controls MCP read timeouts and defaults to 5 seconds on MCPServerStreamableHttp. A scrape, an enrichment waterfall or a slow provider can take longer, so set it to 60 or more.

max_retry_attempts retries list_tools and call_tool automatically. Locus replays an identical execute call made within one minute without a new charge, which limits the cost of a retry, but keep retries low for paid tools and check credits_charged. Set cache_tools_list=True to skip a tool list request on every run.

How do I cap spend per call in the Agents SDK?

Start with the agent key. Its per-call cap is enforced by Locus, so a call priced above it fails with agent_connection_call_limit_exceeded and nothing runs. Then ask the agent to pass max_credits to execute; a call above that ceiling fails with nothing charged.

The model writes max_credits, so add an SDK control too. Local MCP servers accept tool_input_guardrails, which read each call’s arguments and can reject an execute call with no ceiling. require_approval with {"always": {"tool_names": ["execute"]}} pauses every paid call for a person, and leaves free reads alone.

• Agent tool spending controls

What does an Agents SDK research run cost through Locus Pro?

Prices come from the Locus catalog; 1,000 credits equal $1. Search, describe and balance checks are free. Prices checked November 10, 2026.

A run with 1 Firecrawl search and 2 page scrapes costs at most 1.7 + 38.6 + 38.6 = 78.9 credits, about $0.08. 500 runs a month cost at most about $39.45.

If Firecrawl is the only provider you use, it can cost less per call with your own Firecrawl account and API key. Locus Pro pays off when the same agent also calls search, enrichment or data providers you would otherwise sign up for one by one.

• Scrape websites without a subscription

Which errors will the agent see?

By default the SDK turns MCP tool failures into text the model can read. Set failure_error_function to None to raise them as exceptions instead, so your code decides what happens.

When should an Agents SDK app skip Locus Pro?

Skip it when one provider covers the job at steady volume, or when the tool is your own function. That provider’s own key or a function tool is simpler there.

Use it when an agent needs several paid providers behind one key, when calls come in bursts, or when you want a price ceiling on each call and one bill.

• Add Locus to ChatGPT
• Add Locus to any MCP client
• Locus Pro plans