# Connect LlamaIndex to SAM.gov data

To use SAM.gov data in LlamaIndex, create BasicMCPClient("https://samgovapi.io/api/mcp", headers={"Authorization": "Bearer <key>"}), turn it into tools with McpToolSpec(client=...).to_tool_list_async(), and give them to a FunctionAgent. The agent then calls samgovapi tools during its workflow.

LlamaIndex is often used for document-heavy work, such as reading solicitations; adding the samgovapi tools lets the same agent check the registration and award facts the documents mention.

- 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: llama-index-tools-mcp 0.4.8: McpToolSpec listed every tool (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.

## Set up LlamaIndex

1. Install

Terminal:

```bash
pip install llama-index llama-index-tools-mcp
```

2. Build the agent: BasicMCPClient accepts headers for HTTP servers; a URL that is not SSE uses Streamable HTTP.

agent.py:

```python
import asyncio, os
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI
from llama_index.tools.mcp import BasicMCPClient, McpToolSpec

async def main():
    client = BasicMCPClient("https://samgovapi.io/api/mcp", headers={"Authorization": f"Bearer {os.environ['SAMGOVAPI_API_KEY']}"})
    tools = await McpToolSpec(client=client).to_tool_list_async()
    agent = FunctionAgent(name="samgov", description="SAM.gov research", llm=OpenAI(model="gpt-4o"), tools=tools,
                          system_prompt="Quote meta.as_of for every fact.")
    print(await agent.run("Is UEI ZXBCU6K5KL99 registered in SAM.gov, and when does its registration expire?"))

asyncio.run(main())
```

## 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

- If you pass your own http_client to BasicMCPClient, headers and timeout are taken from that client instead.

## Troubleshooting

- Tools list is empty: Check the URL ends in /api/mcp and is https.
- INVALID_API_KEY: The variable was empty when the client was built.
- ONBOARDING_REQUIRED: Answer the onboarding questions once for the account.

## Questions

### Can I limit the tools?

McpToolSpec takes allowed_tools with a list of tool names.

## Official documentation

- llama-index-tools-mcp README: https://github.com/run-llama/llama_index/tree/main/llama-index-integrations/tools/llama-index-tools-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.