SAM.gov Federal Contractor Registry MCP Server

An Apify actor that wraps the System for Award Management (SAM.gov) federal API as a Model Context Protocol (MCP) server. AI assistants and developer tools can query four structured tools to search the federal contractor registry, check exclusions and debarment status, browse contract opportunities, and retrieve full entity registration details.

A SAM.gov API key is required — free registration at sam.gov.

---

What This Actor Does

SAM.gov is the authoritative US government database for:

• Entity registration — every business and individual registered to receive federal contracts or grants
• Exclusions — entities debarred, suspended, or otherwise ineligible for federal awards
• Contract opportunities — active solicitations from every federal agency (formerly FedBizOpps / beta.SAM.gov)

This actor exposes all three resources as an MCP-compliant HTTP server. Connect any MCP-compatible AI client (Claude, LangChain, custom agents) and query the federal contractor ecosystem in real time.

---

MCP Tools Available

Point your MCP client at http://<actor-run-url>:4321 after setting serveMcp: true.

1. search_entities

Search the SAM.gov entity registry by name, UEI, CAGE code, state, or NAICS code.

Parameters:

Name	Type	Required	Description
api_key	string	Yes	Your SAM.gov API key
entity_name	string	No	Legal business name (partial match)
uei	string	No	12-character Unique Entity Identifier
cage_code	string	No	5-character CAGE code
state	string	No	2-letter state code (e.g. CA)
naics_code	string	No	6-digit NAICS code
registration_status	string	No	Active (default), Expired, or empty for all
limit	integer	No	Max results (default 10, max 100)

Returns: List of entity records with: uei, legal_name, registration_status, activation_date, expiration_date, purpose, city, state, zip, country, naics_codes, source.

Example:

{
  "name": "search_entities",
  "arguments": {
    "api_key": "YOUR_KEY",
    "entity_name": "Lockheed Martin",
    "state": "MD"
  }
}

---

2. check_exclusions

Check whether a business or individual is excluded (debarred/suspended) from receiving federal contracts or assistance.

Parameters:

Name	Type	Required	Description
api_key	string	Yes	Your SAM.gov API key
entity_name	string	Conditional	Name to check (provide name or UEI)
uei	string	Conditional	UEI to check directly

Returns: List of exclusion records with: uei, legal_name, exclusion_type, excluding_agency, end_date, country, entity_type, exclusion_program, create_date, update_date, source.

If no exclusions are found: [{"_meta": {"excluded": false, "message": "No exclusions found"}}]

Example:

{
  "name": "check_exclusions",
  "arguments": {
    "api_key": "YOUR_KEY",
    "entity_name": "ACME Corporation"
  }
}

---

3. search_opportunities

Search active federal contract opportunities (solicitations) on SAM.gov.

Parameters:

Name	Type	Required	Description
api_key	string	Yes	Your SAM.gov API key
keyword	string	No	Keyword search in title/description
naics	string	No	NAICS code filter
set_aside	string	No	Set-aside type (e.g. Small Business, 8(a))
posted_from	string	No	Posted on or after date (MM/DD/YYYY)
limit	integer	No	Max results (default 10, max 100)

Returns: List of opportunity records with: notice_id, title, solicitation_number, agency, posted_date, response_deadline, type, naics_code, set_aside, active, source.

Example:

{
  "name": "search_opportunities",
  "arguments": {
    "api_key": "YOUR_KEY",
    "keyword": "cybersecurity",
    "set_aside": "Small Business",
    "limit": 20
  }
}

---

4. get_entity_details

Retrieve complete entity registration details by UEI, including CAGE code, entity structure, mailing address, and points of contact.

Parameters:

Name	Type	Required	Description
api_key	string	Yes	Your SAM.gov API key
uei	string	Yes	12-character UEI

Returns: All fields from search_entities plus: cage_code, duns_number, entity_structure, entity_structure_desc, congressional_district, mailing_address, points_of_contact.

Example:

{
  "name": "get_entity_details",
  "arguments": {
    "api_key": "YOUR_KEY",
    "uei": "LMMFC53NKYK3"
  }
}

---

Running Modes

Batch Mode (default)

Set serveMcp: false (default). The actor performs a one-shot entity search using entityName and/or uei from the input, pushes results to the dataset, and exits.

Input example:

{
  "apiKey": "YOUR_SAM_GOV_API_KEY",
  "entityName": "Raytheon Technologies",
  "limit": 25
}

Edge case: If apiKey is empty, the actor pushes a graceful fallback record with _meta.error = "apiKey required" and exits with SUCCEEDED status (no crash).

MCP Server Mode

Set serveMcp: true. The actor starts an HTTP server on port 4321, pushes one seed entity record to the dataset, and serves tool calls for up to 24 hours.

Input example:

{
  "apiKey": "YOUR_SAM_GOV_API_KEY",
  "serveMcp": true
}

---

MCP Endpoint Reference

Endpoint	Method	Description
/	GET	Health check
/health	GET	Health check
/mcp/tools	GET	List all 4 tools with JSON schemas
/mcp/call	POST	Call a tool by name

Request format:

{
  "name": "search_entities",
  "arguments": {
    "api_key": "YOUR_KEY",
    "entity_name": "Boeing"
  }
}

Response format:

{
  "content": [
    {
      "type": "text",
      "text": "[{\"uei\": \"...\", \"legal_name\": \"...\", ...}]"
    }
  ]
}

---

Getting a SAM.gov API Key

1. Go to https://sam.gov/content/home
2. Create a free account or log in with Login.gov
3. Navigate to System Account under your user profile
4. Request a public API key — approval is usually instantaneous
5. Pass the key as apiKey in actor input or directly in tool arguments

Rate limits on the public API: typically 10 requests/second. The actor does not parallelize requests by default.

---

Use Cases

Federal Vendor Due Diligence

Before awarding a subcontract or entering a teaming agreement, run search_entities to verify active registration and check_exclusions to confirm the entity is not debarred.

Procurement Pipeline Research

Use search_opportunities with keyword and NAICS filters to build automated solicitation alerts for specific industries or set-aside categories.

Compliance Automation

Legal and compliance teams can build automated checks: verify that every vendor in a portfolio maintains active SAM registration and is not on the exclusions list.

AI Agent Procurement Assistant

Connect to Claude as an MCP server. The agent can answer questions like "Show me all active small business set-aside IT opportunities posted in the last 30 days in California" by chaining search_opportunities and search_entities.

Market Intelligence

Analyze which entities are registered in a given NAICS code in a given state. Understand the competitive landscape for a specific federal market segment.

OSINT / Investigative Research

Cross-reference exclusions data with entity names to flag potential compliance issues in a supply chain or investment portfolio.

---

Error Handling

All tools return graceful fallbacks on any error:

[{"_meta": {"error": "description", "fallback_tried": true}}]

The actor never raises unhandled exceptions outward. It always exits SUCCEEDED, even when the SAM.gov API is unavailable or the API key is invalid.

---

Output Dataset Fields (Entity Search)

Field	Type	Description
uei	string	Unique Entity Identifier (12 chars)
legal_name	string	Official legal business name
registration_status	string	Active, Expired, etc.
activation_date	string	Date registration became active
expiration_date	string	Date registration expires
purpose	string	Purpose of registration description
city	string	Physical address city
state	string	2-letter state code
zip	string	ZIP code
country	string	Country code
naics_codes	array	List of registered NAICS codes
source	string	Always sam.gov

---

Technical Details

• Runtime: Python 3.11+
• Framework: Apify SDK v2+
• HTTP client: httpx (async)
• MCP server: asyncio raw TCP, HTTP/1.1
• Port: 4321
• Max server lifetime: 24 hours
• API sections fetched: entityRegistration, coreData, assertions
• Timeout per call: 30 seconds

---

Connecting via Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "sam-gov": {
      "url": "http://<your-actor-run-url>:4321"
    }
  }
}

---

License

Data sourced from SAM.gov is US government public domain. This actor code is MIT licensed.