You can search and read public SAM.gov contract opportunities through this MCP server.
Search contract notices by posted-date range (required in schema, max 1 year), keywords/title, NAICS, set-aside code, state, limit, and offset.
Retrieve full JSON details for one opportunity by notice_id, searching the last year of postings.
List SAM.gov set-aside codes and their meanings.
Use it read-only from MCP clients with your own SAM.gov API key; it does not rank/score, look up entities/UEIs, download attachments, or handle award data.
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., "@sam-gov-mcp Find small-business set-aside IT opportunities in Maryland posted in the last 30 days."
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.
An MCP server that lets AI assistants (Claude Desktop, Cursor, and other MCP clients) search SAM.gov contract opportunities through the public SAM.gov Get Opportunities API.
Read-only. It only searches and reads public notices.
Bring your own key. You supply a free SAM.gov API key in SAM_API_KEY. The key is never logged and is redacted from errors and returned links.
No ranking or scoring. It returns what SAM.gov returns, summarized.
Get a free API key: sign in at sam.gov → Account Details → API Key.
Install. Claude Code:
claude mcp add sam-gov -e SAM_API_KEY=your-key-here -- npx -y @itcustomsolution/sam-gov-mcpOr run it directly: SAM_API_KEY=your-key-here npx -y @itcustomsolution/sam-gov-mcp
Add it to your MCP client. Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"sam-gov": {
"command": "npx",
"args": ["-y", "@itcustomsolution/sam-gov-mcp"],
"env": { "SAM_API_KEY": "your-key-here" }
}
}
}Ask: "Find small-business set-aside opportunities for NAICS 541512 posted in the last 30 days in Maryland."
Related MCP server: Government Contracts MCP
Tool | What it does | Inputs |
| Search notices |
|
| Full JSON for one notice |
|
| Set-aside codes and meanings | none |
Search results are summarized to: noticeId, title, solicitationNumber, agency, postedDate, responseDeadline, type, setAside, naics, state, uiLink.
SAM.gov requires a posted-date range of 1 year or less on every search; the server validates this before calling the API.
Public API keys have daily rate limits set by GSA. Errors from SAM.gov are passed back as tool errors (with the key redacted).
Out of scope: entity/UEI lookup, award data, attachments download, bid/no-bid scoring.
SAM.gov requires the key as an api_key query parameter, so it travels in the request URL to api.sam.gov over HTTPS. The server redacts it from errors, links, and returned JSON, but anything that logs full URLs (an HTTP proxy, for example) would see it.
Notice titles and descriptions are third-party text. Treat them as data, not instructions (prompt injection).
Responses over 5 MB are refused and requests time out after 30 s.
npm install
npm test # vitest, HTTP fully mocked, no key needed
npm run buildNever commit a real key. .env is git-ignored.
MIT © IT Custom Solution
Get full details of one opportunity by noticeId (searches the last year of postings).
| Name | Required | Description | Default |
|---|---|---|---|
| notice_id | Yes | SAM.gov noticeId |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose a real behavioral constraint: results are limited to the last year of postings. However, it says nothing about authentication requirements, not-found behavior, or rate limits, so the disclosure is partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One tight sentence that front-loads the action and the identifying parameter, with the scope caveat in parentheses. Nothing is wasted or buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-record fetch with no output schema, the description should convey what 'full details' entails, but it leaves the return shape entirely unspecified. Combined with zero annotation coverage, the definition is functional but leaves the agent guessing about the payload and error cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single required parameter with 100% schema description coverage, so the schema already documents noticeId fully. The description adds no format or sourcing detail (e.g., where to obtain the ID) beyond the schema, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (get full details of one opportunity) and identifies the key input (noticeId), which is clearly distinct from the sibling search_opportunities. It does not explicitly name the sibling it contrasts with, but the singular-vs-search distinction is obvious.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: fetching a single record by ID naturally follows a search that yields that ID, and no alternative or exclusion is named. It adds a useful scoping hint (only the last year of postings) but gives no explicit when-to-use/when-not-to-use guidance relative to search_opportunities.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List SAM.gov set-aside codes and their meanings.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden, but the operation is a trivial zero-parameter read of static reference data, so little disclosure is required. It states what is returned (codes and meanings) but says nothing about completeness, caching, or format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler; the resource and its payload are stated immediately and nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, zero-parameter reference lookup with no output schema and no annotations, the description is sufficient to call the tool correctly. Only the exact return shape is unspecified, which is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing to document; the baseline for a no-parameter tool is 4. The description adds no parameter guidance because none is possible.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List SAM.gov set-aside codes') plus the returned content (their meanings). This clearly distinguishes it from the opportunity-centric siblings, though it never explicitly names them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: an agent infers this is a reference lookup to use when interpreting a set-aside code. There is no explicit when-to-use statement, no mention of alternatives, and no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search SAM.gov contract opportunities. Read-only. Posted date range is required (max 1 year).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 10) | |
| naics | No | NAICS code, e.g. 541512 | |
| state | No | Place of performance state, 2-letter code | |
| offset | No | ||
| keywords | No | Words to match in the opportunity title | |
| posted_to | Yes | End date, YYYY-MM-DD or MM/DD/YYYY | |
| set_aside | No | Set-aside code, e.g. SBA, 8A, SDVOSBC (see list_set_aside_codes) | |
| posted_from | Yes | Start date, YYYY-MM-DD or MM/DD/YYYY |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden; it does disclose 'Read-only' and the required date-range constraint, which is real behavioral value. However, it says nothing about pagination behavior, result caps, or auth/rate limits, leaving meaningful gaps for a search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, zero waste, with the core purpose and the hard requirement front-loaded. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description must carry more weight. It covers purpose, read-only status, and the required range, but omits pagination (offset/limit) behavior and any note on result shape, leaving an agent partially equipped.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (88%), so the schema already documents most parameters, and a baseline of 3 applies. The description adds the 'max 1 year' range constraint not present in the schema, but does not explain the undocumented offset parameter or clarify limit defaults beyond what the schema states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Search') and resource ('SAM.gov contract opportunities'), which naturally contrasts with the singular sibling get_opportunity. It does not explicitly name alternatives, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives one concrete usage constraint — a posted date range is required and capped at 1 year — but offers no guidance on when to prefer this over get_opportunity or how list_set_aside_codes fits in. Usage is implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_opportunitylist_set_aside_codessearch_opportunitiesScored across 3 tools
search_opportunities and get_opportunity are clearly distinguished by action and input (query vs noticeId), and list_set_aside_codes is a separate reference function. No overlapping purposes or ambiguous boundaries.
All names follow a consistent snake_case verb_noun pattern: search_opportunities, get_opportunity, list_set_aside_codes. The convention is predictable and readable.
Three tools are well-scoped for a focused read-only SAM.gov opportunity server; search, detail retrieval, and set-aside reference each earn their place. The count is minimal but not thin given the narrow domain.
The surface covers the core read-only workflow: find opportunities, retrieve one by ID, and decode set-aside codes. Minor gaps exist (e.g., other reference lists like NAICS or agency filters), but no critical dead ends for the stated purpose.
Search U.S. federal contract opportunities (RFPs, bids, awards) from SAM.gov official data.
Search US grants + federal contracts (Grants.gov + SAM.gov) from any LLM.
SAM.gov contract opportunities and entity lookup (BYOK) plus USASpending federal award data.
US government data as clean JSON for AI agents: SAM.gov contract opportunities, USAspending awards, Grants.gov grants, House STOCK Act trades, and SEC EDGAR filings (Form 4 insider trades, 8-K events, 13F holdings, 13D/G stakes, XBRL fundamentals, 10-K/10-Q sections). 19 read-only tools. Data is as fresh as each source publishes; congressional trades lag up to 45 days and report dollar ranges (House only). Free tier, no card.
