# Connect Claude Code to SAM.gov data

To connect Claude Code to SAM.gov data, run claude mcp add --transport http samgovapi https://samgovapi.io/api/mcp with an Authorization: Bearer header, or commit a .mcp.json that reads the key from SAMGOVAPI_API_KEY. Claude Code then lists the samgovapi tools in /mcp and calls registration_status, search_opportunities and the rest on its own.

Claude Code is the fastest way to put federal contracting data inside a codebase: it can write the script that checks your supplier list, run it, and fix it, while answering one-off questions through the MCP tools. A project-scoped .mcp.json means everyone who clones the repo gets the server, and each person brings their own key through the environment.

- 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: Claude Code 2.1.300, project .mcp.json with ${SAMGOVAPI_API_KEY} in the header (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. Keep the key in the SAMGOVAPI_API_KEY environment variable and reference it as ${SAMGOVAPI_API_KEY} in .mcp.json. Claude Code also accepts ${VAR:-default} for a fallback.

## Set up Claude Code

1. Export your key: Claude Code reads environment variables when it starts, so export the key in the shell profile you launch it from.

Shell:

```bash
export SAMGOVAPI_API_KEY="sg_..."
```

2. Add the server for yourself: The --transport http flag selects Streamable HTTP, which this server speaks. Double quotes let your shell put the key into the stored config; the default scope is local to this project directory.

Terminal:

```bash
claude mcp add --transport http samgovapi https://samgovapi.io/api/mcp \
  --header "Authorization: Bearer $SAMGOVAPI_API_KEY"
```

3. Or share it with the repo: A .mcp.json at the repository root is checked in. Claude Code expands ${VAR} in url and headers at startup, so the file never contains a key. Each teammate approves the project server the first time it loads.

.mcp.json:

```json
{
  "mcpServers": {
    "samgovapi": {
      "type": "http",
      "url": "https://samgovapi.io/api/mcp",
      "headers": {
        "Authorization": "Bearer ${SAMGOVAPI_API_KEY}"
      }
    }
  }
}
```

4. Confirm the connection: claude mcp list should show the server as Connected. Inside a session, /mcp lists its tools.

Terminal:

```bash
claude mcp list
claude mcp get samgovapi
```

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

- Project-scope servers ask each user for approval on first use; claude mcp reset-project-choices clears earlier answers.
- If the variable is unset, Claude Code still loads the file, warns in claude mcp list, and sends the literal text, which the server rejects with INVALID_API_KEY.

## Troubleshooting

- claude mcp list shows Pending approval: Start claude in the project directory and approve the samgovapi server when asked.
- Tools answer INVALID_API_KEY: The header arrived without a valid key. Check echo $SAMGOVAPI_API_KEY in the shell that launched Claude Code, then restart it.
- A data tool answers ONBOARDING_REQUIRED: Ask Claude to set up your samgovapi account: it calls get_onboarding_questions and answer_onboarding once, at no cost.

## Questions

### Should the server be local, project or user scope?

Use project scope with .mcp.json for a repository that works with federal data, user scope (-s user) if you want the tools in every project.

### Can Claude Code write scripts against the REST API too?

Yes. The same key works for https://samgovapi.io/api/v1; ask it to read /openapi.json and write the client.

## Official documentation

- Claude Code: connect to MCP servers: https://code.claude.com/docs/en/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.