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

```bash
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:

```json
{
  "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](https://sam.gov) under **Account Details → Public API
Key**, then:

```bash
export SAM_API_KEY=your-key
npm run build
```

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

```json
{
  "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](https://github.com/juanmplazasg-lgtm/agent-evals).

MIT.