Skip to main content
Glama

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

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.

Available Tools

5 tools
fetch_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

    A4.4/5.0

    Scored across 5 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      The 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.
      153
      238 npm
      19
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      MCP 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.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Read-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.
      12
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for searching government tenders from CanadaBuys and SAM.gov with free stats and paid search, latest, and AI matching tools using x402 micropayments.
      4
      1
      MIT