samgov-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@samgov-mcp Find recent federal contract opportunities for IT services in Virginia"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 stdioRun 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
Tool | What it does |
| Search a posted-date window. Filters for NAICS, procurement type, set-aside, state, title |
| One notice by its exact solicitation number |
| The downloadable resource links for one notice |
| Download one attachment |
| 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 buildClaude 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 |
| none | Free key from SAM.gov. Its presence is what selects live mode |
| auto |
|
|
| Upstream request timeout |
|
| Refuse attachments larger than this rather than filling a context window |
Notes on the upstream
postedFromandpostedToare 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
descriptionfield, not prose. It is returned asdescription_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.
Available Tools
5 toolsfetch_attachmentDownload one attachmentA
Downloads a single attachment by its resource URL, as returned by list_attachments. Returns UTF-8 text when the document is text, and otherwise returns the content type and byte length without guessing at the contents. Binary formats such as PDF are reported, not silently decoded into noise.
Inputs: url (required).
get_solicitationGet one SAM.gov solicitationA
Retrieves a single notice by its solicitation number, within a posted-date window. Abstains explicitly when the number is not found in that window, because 'not in this window' and 'does not exist' are different answers.
Inputs: postedTo (required), postedFrom (required), solicitationNumber (required).
list_attachmentsList attachments for a solicitationA
Returns the downloadable attachment URLs for one notice. An empty list means the notice carries no attachments, which is a real and common state and is reported as zero rather than as an error.
Inputs: postedTo (required), postedFrom (required), solicitationNumber (required).
search_solicitationsSearch SAM.gov solicitationsA
Searches federal contract opportunities in a posted-date window. postedFrom and postedTo are required, MM/dd/yyyy, at most one year apart. Returns normalised notices, each with its attachment links. The returned count is the length of the list actually returned, which is not the same as totalRecords across all pages.
Inputs: postedTo (required), postedFrom (required), limit, ncode, +5 more.
server_statusServer statusA
Reports which mode the server is in and where its data is coming from. Call this first when results look surprising.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clearly distinct role: searching solicitations, retrieving a single solicitation, listing attachments, fetching an attachment, and checking server status. No two tools could be confused for the same purpose.
Most tools follow the verb_noun pattern (fetch_attachment, get_solicitation, list_attachments, search_solicitations). server_status deviates as a noun phrase but is still logically named and not confusing.
The 5 tools are well-scoped for a focused read-only SAM.gov API server. Each tool serves a distinct need without redundancy or bloat.
The tool set covers the full read lifecycle: search and retrieve notices, list and download attachments, and diagnose issues with server status. No obvious missing operations given the domain.
Maintenance
Related MCP Connectors
MCP server for the GovContractScout US government contracts API: search, NAICS, match scoring.
B2B, GovCon & LegalTech MCP server for live RFPs, contract parsing, compliance & proposal tools.
MCP access to the U.S. federal procurement graph: contracts, opportunities, entities, and more.
Federal+SLED govcon MCP: SAM, USASpending, recompete, hearings, policy intel, search. Private AI.
Related MCP Servers
- AlicenseAqualityBmaintenanceThe most comprehensive keyless federal-data MCP server. 36 tools for SAM.gov + USAspending + Federal Register + eCFR + Grants.gov. No API key, no registration, no signup. Works in Claude Desktop, Claude Code, Codex CLI, Cursor, Continue, Gemini CLI, and any MCP-aware host.153238 npm19MIT
- FlicenseNot gradedqualityCmaintenanceMCP server for querying U.S. Federal Procurement Data System (FPDS-NG) to search federal contract actions by keyword, agency, NAICS, or vendor, with USDC micropayments via x402.-
- AlicenseAqualityDmaintenanceRead-only MCP server for exploring US federal spending data via the USAspending.gov API, enabling natural language queries on awards, agencies, recipients, and spending trends.12MIT
- AlicenseAqualityDmaintenanceMCP server for searching government tenders from CanadaBuys and SAM.gov with free stats and paid search, latest, and AI matching tools using x402 micropayments.41MIT