# Connect Mastra to SAM.gov data

To use SAM.gov data in Mastra, create an MCPClient with a samgovapi server whose url is new URL("https://samgovapi.io/api/mcp") and whose requestInit.headers carry Authorization: Bearer <key>, then pass await mcp.listTools() to your Agent. Tool names are namespaced, such as samgovapi_registration_status.

Mastra workflows are a good home for scheduled contracting jobs, such as a weekly recompete scan, because each step can call one samgovapi tool and pass the result on.

- 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: @mastra/mcp 2.9.0: listTools returned every tool, namespaced samgovapi_<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 process.env.SAMGOVAPI_API_KEY.

## Set up Mastra

1. Install

Terminal:

```bash
npm install @mastra/mcp @mastra/core
```

2. Create the client and agent: A url means Streamable HTTP.

agent.ts:

```ts
import { MCPClient } from "@mastra/mcp";
import { Agent } from "@mastra/core/agent";

export const mcp = new MCPClient({
  id: "samgovapi",
  servers: {
    samgovapi: {
      url: new URL("https://samgovapi.io/api/mcp"),
      requestInit: { headers: { Authorization: `Bearer ${process.env.SAMGOVAPI_API_KEY}` } },
    },
  },
});

export const agent = new Agent({
  id: "samgov-agent",
  name: "SAM.gov agent",
  instructions: "Answer with samgovapi tools and quote meta.as_of.",
  model: "openai/gpt-5",
  tools: await mcp.listTools(),
});
```

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

- Older Mastra code used getTools(); current docs use listTools().

## Troubleshooting

- Tool names do not match the docs: Mastra prefixes the server name: samgovapi_search_opportunities.
- INVALID_API_KEY: Set the variable before the module that creates the client loads.
- ONBOARDING_REQUIRED: Answer the onboarding questions once for the account.

## Questions

### Should I disconnect?

Call mcp.disconnect() when a script ends; long-running servers keep the client.

## Official documentation

- Mastra: MCPClient reference: https://mastra.ai/reference/tools/mcp-client

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.