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.

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

Tool	What it does
search_solicitations	Search a posted-date window. Filters for NAICS, procurement type, set-aside, state, title
get_solicitation	One notice by its exact solicitation number
list_attachments	The downloadable resource links for one notice
fetch_attachment	Download one attachment
server_status	Which mode it is in and where the data is coming from

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

Variable	Default	Meaning
SAM_API_KEY	none	Free key from SAM.gov. Its presence is what selects live mode
SAM_MODE	auto	live or fixtures, overriding the default
SAM_TIMEOUT_MS	20000	Upstream request timeout
SAM_MAX_ATTACHMENT_BYTES	8000000	Refuse attachments larger than this rather than filling a context window

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.