Metadata-Version: 2.5
Name: sam-gov-mcp
Version: 1.0.6
Summary: MCP server for SAM.gov entity registration, exclusion, contract opportunity, and contract award data
Project-URL: Homepage, https://1102tools.com
Project-URL: Repository, https://github.com/1102tools/federal-contracting-mcps
Project-URL: Issues, https://github.com/1102tools/federal-contracting-mcps/issues
Author: James Jenrette / 1102tools
License: MIT
Keywords: 1102,FPDS,contract-awards,debarment,exclusions,federal-contracts,mcp,model-context-protocol,procurement,sam.gov
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: filelock>=3.13
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp<3,>=2.0.0
Requires-Dist: platformdirs>=4.0
Description-Content-Type: text/markdown

# sam-gov-mcp

<!-- mcp-name: io.github.1102tools/sam-gov-mcp -->

MCP server for SAM.gov entity registration, exclusion/debarment, contract opportunity, contract award, federal hierarchy, and FFATA subaward data.

Requires a free SAM.gov API key. MCP is an open standard: this server runs in any MCP client, not just Claude. Executed and verified on eleven platforms in August 2026 (see [Configuration](#configuration)).

*Tested and hardened through ten audit rounds including a ~230-call paced live campaign. 1,136 regression tests. v0.4 added 278 tests for Federal Hierarchy + FFATA Subaward endpoints (123 live), catching three silently-ignored Subaward API parameter casings during live audit. Birthplace of the `extra='forbid'` cross-fix applied to all 8 MCPs in the suite. See [testing.md](testing.md) for the full testing record.*

## What it does

Exposes seven SAM.gov REST APIs as 19 MCP tools:

**Entity Management (v3)**
- `lookup_entity_by_uei` - Single UEI lookup with configurable response sections
- `lookup_entity_by_cage` - CAGE code lookup
- `search_entities` - Flexible entity search (NAICS, PSC, business type, state, name, etc.)
- `get_entity_reps_and_certs` - FAR/DFARS reps and certs (must be requested explicitly)
- `get_entity_integrity_info` - FAPIIS proceedings data

**Exclusions (v4)**
- `check_exclusion_by_uei` - Single-UEI debarment check
- `search_exclusions` - Broader exclusion search by name, classification, program, agency, date

**Contract Opportunities (v2)**
- `search_opportunities` - Search contract opportunities with full working filter set
- `get_opportunity_description` - Fetch the HTML description by notice ID

**Contract Awards (v1) -- FPDS replacement**
- `search_contract_awards` - Search contract award records (vendor, agency, NAICS, dates, dollars, set-aside, etc.)
- `lookup_award_by_piid` - Look up all modifications for a single PIID
- `search_deleted_awards` - Search deleted award records for audit trails

**Federal Hierarchy (v1)**
- `search_federal_organizations` - Search the FH for departments, agencies, sub-agencies, offices (filter by FH org id, name, type, status, agency code, CGAC)
- `get_organization_hierarchy` - Walk the children of a federal organization

**Acquisition Subaward Reporting (FFATA subcontracts)**
- `search_acquisition_subawards` - Search FFATA subcontract reports (prime/sub relationships, agency, dates, status)

**Assistance Subaward Reporting (FFATA grant subawards)**
- `search_assistance_subawards` - Search FFATA grant subaward reports (FAIN, prime award key, agency, dates)

**PSC Lookup**
- `lookup_psc_code` - Resolve a PSC code to its full record
- `search_psc_free_text` - Free-text PSC discovery

**Composite workflow**
- `vendor_responsibility_check` - One-shot FAR 9.104-1 check (entity + exclusions in a single tool call)

## Authentication

Requires a SAM.gov API key set via the `SAM_API_KEY` environment variable.

Get a free key at [sam.gov/profile/details](https://sam.gov/profile/details) under "Public API Key."

| Account Type | Daily Limit |
|---|---|
| Non-federal, no SAM role | 10/day |
| Non-federal with SAM role | 1,000/day |
| Federal personal | 1,000/day |
| Federal system account | 10,000/day |

**Important: SAM.gov API keys expire every 90 days.** Regenerate at the same profile page and update your env var. This server returns a clear actionable error on 401/403 with regeneration instructions.

## Installation

### Via uvx (recommended)

```bash
uvx sam-gov-mcp
```

### Via pip

```bash
pip install sam-gov-mcp
```

### From source

```bash
git clone https://github.com/1102tools-dev/federal-contracting-mcps.git
cd federal-contracting-mcps/servers/sam-gov-mcp
pip install -e .
```

## Configuration

MCP is an open standard, and this config was executed and verified in August 2026 on eleven platforms: Claude Desktop, Claude Code, Codex Desktop and CLI, Gemini via Antigravity, GitHub Copilot CLI, DeepSeek Harness, Grok Build, Cursor, opencode, and LibreChat. Most clients take the same JSON block below and differ only in where the config file lives; the [universal setup guide (PDF)](https://1102tools.com/downloads/1102tools-universal-setup.pdf) has the exact file path and format for every platform, including the Codex TOML form.

```json
{
  "mcpServers": {
    "sam-gov": {
      "command": "uvx",
      "args": ["--refresh-package", "sam-gov-mcp", "--from", "sam-gov-mcp", "sam-gov-mcp"],
      "env": {
        "SAM_API_KEY": "SAM-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      }
    }
  }
}
```

The `--refresh-package` flag tells uv to check PyPI for a newer release each time your client launches the server, so fixes arrive automatically; without it, uv keeps serving whatever version it first cached. It adds a moment of network time at startup, so raise your platform's MCP startup timeout if it enforces a short one.

Restart the client and the tools appear.

## Example prompts

Once configured (these mirror the field-tested set in the
[1102tools prompt guide](https://1102tools.com/downloads/1102tools-prompt-guide.pdf)):

- "Run a vendor responsibility check on [UEI] for registration status and exclusions, then pull FAPIIS integrity records separately; the one-pass check does not include those."
- "Pull [COMPANY]'s registration status, socioeconomic categories, and any exclusions. If SAM returns multiple registrations for one UEI, say so and list them before picking one."
- "Get [COMPANY]'s FAR 52.212-3 and DFARS 252.204-7016 answers from their reps and certs (summary mode), and flag anything a contracting officer would want to read in full text."
- "How far back does [COMPANY]'s federal award history actually go? Check contract awards decade by decade, FY1970 forward; volumes thin out before 1980, so read single-digit years as archival traces, not gaps."
- "Find active 8(a)-certified firms (SBA-certified, not self-designated) in [STATE] under NAICS [NAICS]."
- "Search sources sought notices from the last 30 days under NAICS [NAICS], response deadlines sorted soonest first."
- "Show me SDVOSB set-aside solicitations for IT services posted this quarter."
- "Get the full description of notice ID [paste ID] and summarize the SOW."
- "Search exclusions for [NAME]: give me classification (Firm, Individual, Vessel), excluding agency, and whether each record is active."
- "Search contract awards for [COMPANY] in fiscal year 2026, then look up all modifications for the biggest PIID you find."
- "Show me deleted contract award records for Department of Defense this fiscal year."
- "Find the Federal Hierarchy ID for the Department of the Treasury and walk one level of children."
- "Show me FFATA subcontracts on prime PIID [PIID], and total the subaward amounts."
- "Pull all subawards reported under grant FAIN [FAIN]."
- "List the agency-level orgs in CGAC 075 (HHS)."

## Design notes

- **Authentication via env var only.** `SAM_API_KEY` is read from the environment on every call. The key never enters the model's conversation context.
- **90-day expiration awareness.** 401/403 errors are translated into an actionable "regenerate at sam.gov/profile/details" message with full context.
- **API quirks baked in as safety rails.**
  - Entity Management hard cap of size=10 is enforced client-side with a clear error
  - Exclusions uses `size` not `limit` (different from other SAM endpoints)
  - Country codes are validated as 3-character ISO alpha-3 (2-char codes return 0 silently)
  - No `Accept: application/json` header is set (Exclusions returns 406 if present)
  - Bracket/tilde/exclamation characters are preserved in query strings for multi-value params
- **Post-filtering for broken parameters.** The Opportunities API silently ignores `deptname` and `subtier` filters. `search_opportunities` exposes an `agency_keyword` parameter that post-filters results by matching `fullParentPathName` substring.
- **includeSections defaults.** Entity lookups default to `entityRegistration,coreData`. Always include `entityRegistration` alongside any other section or the response has no identification. `repsAndCerts` and `integrityInformation` require explicit tool calls (`get_entity_reps_and_certs`, `get_entity_integrity_info`) because even `includeSections=All` doesn't include them.
- **Contract Awards response normalization.** The Contract Awards API returns different JSON wrapper shapes for populated vs. empty results. All tools normalize this to a consistent `{"awardSummary": [...], "totalRecords": int}` shape. Error responses are plain text (not JSON), detected and raised as actionable errors.
- **Contract Awards pagination.** Uses `limit`/`offset` (NOT `page`/`size` like Entity Management). Max limit is 100. Dates must be MM/dd/yyyy format with bracket ranges `[MM/dd/yyyy,MM/dd/yyyy]`.
- **Composite workflow.** `vendor_responsibility_check` collapses a typical FAR 9.104-1 check (entity registration + exclusion lookup) into one tool call, returning a structured flags list for downstream reasoning.
- **Federal Hierarchy quirks baked in.**
  - Lowercase `totalrecords` and `orglist` keys (rest of SAM.gov uses camelCase); normalizer preserves both
  - Default response is ACTIVE-only; passing `status=ACTIVE` is a no-op vs. the unfiltered call. Pass `INACTIVE` to expand to retired orgs
  - Real `fhorgtype` values look like `Department/Ind. Agency`, but the API also accepts shorthand (DEPARTMENT, AGENCY) with case-insensitive matching
- **Subaward Reporting quirks baked in.**
  - Dates use ISO `yyyy-MM-dd` (NOT `MM/dd/yyyy` like Contract Awards). Mixing them raises a clear pre-network validation error
  - Pagination uses `pageNumber`/`pageSize` (NOT `page`/`size` or `limit`/`offset`)
  - Live audit (April 2026) found three documented parameter casings are silently ignored: `PIID` is dropped (use lowercase `piid`), `referencedIdvPIID` is dropped (use `referencedIDVPIID`), and `referencedIDVAgencyID` is dropped (use `referencedIDVAgencyId`). Wire-level names are now correct in the server

## Part of

[federal-contracting-mcps](https://github.com/1102tools-dev/federal-contracting-mcps): monorepo of 8 MCP servers for federal contracting data. Companion to [federal-contracting-skills](https://github.com/1102tools-dev/federal-contracting-skills).

## Request pacing

Every request, including composite-tool subrequests, uses a provisional
3-second cross-process anti-burst interval by default. The local gate uses a
one-way key fingerprint and never stores the raw SAM key. It does not create
additional daily quota or coordinate the same key on another computer.
Override with `FEDERAL_API_MIN_INTERVAL_SECONDS`, use `0` to deliberately
disable it, and use `FEDERAL_API_PACING_DIR` to relocate local pacing state.

## License

MIT
