# Connect OpenAI Agents SDK to SAM.gov data

To use SAM.gov data in the OpenAI Agents SDK, open an MCPServerStreamableHttp with params url https://samgovapi.io/api/mcp and headers carrying your Bearer key, and pass it to Agent(mcp_servers=[...]). The agent lists the samgovapi tools at run time and calls them like local functions.

The Agents SDK can either connect to the server from your process (MCPServerStreamableHttp) or ask OpenAI to call it during a Responses request (HostedMCPTool). Connecting from your process keeps the key inside your infrastructure and lets you cache the tool list.

- Connects with: MCP
- MCP server: https://samgovapi.io/api/mcp
- REST base: https://samgovapi.io/api/v1
- Auth: Authorization: Bearer <key>, kept in SAMGOVAPI_API_KEY
- Tested: openai-agents 0.24.0: list_tools returned every tool and call_tool reached the server (2026-11-13)

## Get a key

Free key at https://samgovapi.io/sign-up, or have the agent call start_signup and approve the link it shows you. Read SAMGOVAPI_API_KEY from the environment in your code; never hard-code it.

## Set up OpenAI Agents SDK

1. Install: Python 3.10 or later.

Terminal:

```bash
pip install openai-agents
```

2. Connect and run: cache_tools_list avoids a tools/list round trip on every run.

agent.py:

```python
import asyncio, os
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    async with MCPServerStreamableHttp(
        name="samgovapi",
        params={"url": "https://samgovapi.io/api/mcp", "headers": {"Authorization": f"Bearer {os.environ['SAMGOVAPI_API_KEY']}"}, "timeout": 30},
        cache_tools_list=True,
    ) as server:
        agent = Agent(name="Contracts analyst", instructions="Quote meta.as_of for every fact.", mcp_servers=[server])
        result = await Runner.run(agent, "Is UEI ZXBCU6K5KL99 registered in SAM.gov, and when does its registration expire?")
        print(result.final_output)

asyncio.run(main())
```

3. Hosted alternative: HostedMCPTool hands the server to OpenAI's Responses API; its tool_config is the Responses mcp tool object, so the key goes in headers.

Python:

```python
from agents import HostedMCPTool

samgov = HostedMCPTool(tool_config={
    "type": "mcp", "server_label": "samgovapi", "server_url": "https://samgovapi.io/api/mcp",
    "headers": {"Authorization": f"Bearer {os.environ['SAMGOVAPI_API_KEY']}"}, "require_approval": "never",
})
```

## Finish account setup once

Data tools unlock after the account answers its onboarding questions: ask the agent to set up your samgovapi account (get_onboarding_questions, then answer_onboarding). Free.

## Check that it works

Ask: "Is UEI ZXBCU6K5KL99 registered in SAM.gov, and when does its registration expire?"

Expected tool call:

```json
{"name":"registration_status","arguments":{"id":"ZXBCU6K5KL99","user_request":"check a registration and its expiry"}}
```

## Things to know

- The default client session timeout is short; raise timeout for large award searches.

## Troubleshooting

- Timeouts on list_tools: Raise params timeout and client_session_timeout_seconds.
- Tool results say INVALID_API_KEY: The environment variable is empty in the process; check os.environ['SAMGOVAPI_API_KEY'].
- ONBOARDING_REQUIRED: Call get_onboarding_questions and answer_onboarding once for the account, or let the agent do it when asked.

## Questions

### Local or hosted MCP?

Local keeps the key in your process and works with any model; hosted saves a hop when you already use the Responses API.

## Official documentation

- OpenAI Agents SDK: MCP: https://openai.github.io/openai-agents-python/mcp/

Checked 2026-11-13. All guides: https://samgovapi.io/agents.md

Independent. Not affiliated with, endorsed by or sponsored by GSA, SAM.gov or any U.S. government agency. Registering in SAM.gov is free at sam.gov.