samgov-mcp

An MCP server over the SAM.gov Contract Opportunities API, built for agents that have to read United States federal solicitations and then be believed about what they read.

Everything this server returns carries the exact URL it came from. Anything SAM.gov did not send comes back as null with its name listed, never as a zero, an empty string, or a plausible guess.

npm install
npm run smoke     # 20 checks, no API key, no network
npm run dev       # starts the server on stdio

Run it with no key and it serves recorded fixtures, so you can inspect every tool contract before signing up for anything.

Why this exists

I build AI systems that live inside a company's operation and answer from its own data. The failure that costs you the room is never a model that underperforms. It is a confident number nobody can trace back to anything.

An MCP server is where that gets decided. By the time a figure reaches the model it is just a token, and no prompt reliably repairs a tool that quietly returned the wrong record. So the discipline goes in the tool layer, where it can be tested.

Related MCP server: fpds-mcp

The envelope

Every result has the same shape:

{
  "source": {
    "url": "https://api.sam.gov/opportunities/v2/search?postedFrom=07%2F01%2F2026&...&api_key=REDACTED",
    "retrieved_at": "2026-08-07T18:33:52.792Z",
    "mode": "live"
  },
  "data": { "returned": 2, "total_records_upstream": 412, "notices": [ ... ] },
  "missing": ["notices[1].response_deadline", "notices[1].set_aside_code"],
  "abstained": { "reason": "..." }
}

source is the request that produced the payload, with the API key stripped so a transcript never leaks a credential.

missing names every field the upstream did not provide. SAM.gov signals "not provided" three different ways, null, "", and an object whose inner name is "", and a model cannot tell those apart from real values. They all become null here, and they all get named.

abstained appears when the server declines. "I could not find this" and "this does not exist" are different answers, and collapsing them into an empty list is how an agent ends up telling somebody a solicitation was cancelled when it was simply posted outside the window it searched.

data.returned is counted off the array actually being returned. total_records_upstream is reported beside it, separately, because they are different numbers and mixing them is how a report claims a pipeline processed 412 documents when it read 10.

Tools

Two things I got wrong, written down

1 · A 404 from this gateway means the key is bad, not the path.

api.sam.gov answers 404 with an empty body for every path when the API key is missing or unrecognised, including paths that exist. DEMO_KEY does not work, because SAM.gov runs its own gateway rather than the shared api.data.gov one. I spent a while probing endpoint variants before realising the endpoint was never the problem. The client now says so in the error text, because the obvious reading of a 404 sends you somewhere useless.

2 · The first version of this server did the exact thing it was built to prevent.

get_solicitation originally ended with ?? rows[0], a harmless-looking fallback: if the exact number is not found, use the first result. But SAM.gov's solnum filter is fuzzy and returns neighbouring notices. So for any number that did not exist, the server would have confidently handed back a different solicitation under the number that was asked for. Different deadline, different set-aside, different scope.

The smoke test did not catch it, because I had asserted that the call returned something. It now asserts abstention, and the abstention message names the neighbours it refused to pass off:

No notice numbered exactly "DOES-NOT-EXIST-0000" was posted between 07/01/2026 and 07/31/2026.
The search returned 2 nearby notice(s) which are NOT this one: FIXTURE-70FA-26-R-0001, ...

It is the same lesson as the first run of any eval suite. The first pass grades your harness, not the thing you pointed it at.

Use it

Live. Generate a free key at sam.gov under Account Details → Public API Key, then:

export SAM_API_KEY=your-key
npm run build

Claude Desktop or Claude Code, in claude_desktop_config.json or via claude mcp add:

{
  "mcpServers": {
    "samgov": {
      "command": "node",
      "args": ["/absolute/path/to/samgov-mcp/dist/index.js"],
      "env": { "SAM_API_KEY": "your-key" }
    }
  }
}

Fixtures. Omit SAM_API_KEY and it runs offline against fixtures/search.json, which is synthetic and labelled as such inside the file. Every tool contract, the grounding envelope and both abstention paths are exercised without a credential. SAM_MODE=live|fixtures overrides the default.

Environment

Notes on the upstream

• postedFrom and postedTo are mandatory, MM/dd/yyyy, at most one year apart. This server refuses other formats at the schema rather than reformatting them, so a wrong window fails loudly instead of silently returning the wrong year.

• SAM.gov puts a URL in the description field, not prose. It is returned as description_link, so an agent does not quote a link as if it were the scope of work.

• Attachments in binary formats are reported with their content type and byte length rather than being decoded into noise. Extracting fields from fillable government forms is a separate step and is deliberately not guessed at here.

Status

Working: the five tools, the grounding envelope, both abstention paths, fixtures mode, 20 smoke checks over the real MCP stdio protocol driven by the reference client.

Next: requirement extraction from fillable PDFs into schema-validated JSON, where every extracted field carries the page and span it came from, plus an eval suite over that extraction using the harness in agent-evals.

MIT.