# SAM.gov Federal Contractor Registry MCP — Entity & Exclusions (`andrew_avina/sam-gov-mcp`) Actor 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 ... - **URL**: https://apify.com/andrew\_avina/sam-gov-mcp.md - **Developed by:** [Andrew Avina](https://apify.com/andrew_avina) (community) - **Categories:** MCP servers, Business - **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing $3.00 / 1,000 result item returneds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## 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](https://sam.gov/content/home). --- ### 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://: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:** ```json { "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:** ```json { "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:** ```json { "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:** ```json { "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:** ```json { "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:** ```json { "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:** ```json { "name": "search_entities", "arguments": { "api_key": "YOUR_KEY", "entity_name": "Boeing" } } ``` **Response format:** ```json { "content": [ { "type": "text", "text": "[{\"uei\": \"...\", \"legal_name\": \"...\", ...}]" } ] } ``` *** ### Getting a SAM.gov API Key 1. Go to 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: ```json [{"_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`: ```json { "mcpServers": { "sam-gov": { "url": "http://:4321" } } } ``` *** ### License Data sourced from SAM.gov is US government public domain. This actor code is MIT licensed. # Actor input Schema ## `apiKey` (type: `string`): Your SAM.gov API key. Obtain free at https://sam.gov/content/home. Required for all API calls. ## `serveMcp` (type: `boolean`): If true, starts the MCP HTTP server on port 4321 for real-time tool calls. Leave false for one-shot batch entity lookup. ## `entityName` (type: `string`): Legal business name to search (partial match supported). Used in batch mode. ## `uei` (type: `string`): Unique Entity Identifier (12-character code) for direct entity lookup. ## `limit` (type: `integer`): Maximum number of entity records to return in batch mode (default 10). ## Actor input object example ```json { "serveMcp": false, "limit": 10 } ``` # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("andrew_avina/sam-gov-mcp").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("andrew_avina/sam-gov-mcp").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{}' | apify call andrew_avina/sam-gov-mcp --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=andrew_avina/sam-gov-mcp", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "SAM.gov Federal Contractor Registry MCP — Entity & Exclusions", "description": "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 ...", "version": "0.1", "x-build-id": "iJMeEWcMqPh20bDuf" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/andrew_avina~sam-gov-mcp/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-andrew_avina-sam-gov-mcp", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/andrew_avina~sam-gov-mcp/runs": { "post": { "operationId": "runs-sync-andrew_avina-sam-gov-mcp", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/andrew_avina~sam-gov-mcp/run-sync": { "post": { "operationId": "run-sync-andrew_avina-sam-gov-mcp", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "apiKey": { "title": "SAM.gov API Key", "type": "string", "description": "Your SAM.gov API key. Obtain free at https://sam.gov/content/home. Required for all API calls." }, "serveMcp": { "title": "Serve MCP", "type": "boolean", "description": "If true, starts the MCP HTTP server on port 4321 for real-time tool calls. Leave false for one-shot batch entity lookup.", "default": false }, "entityName": { "title": "Entity Name", "type": "string", "description": "Legal business name to search (partial match supported). Used in batch mode." }, "uei": { "title": "UEI", "type": "string", "description": "Unique Entity Identifier (12-character code) for direct entity lookup." }, "limit": { "title": "Result Limit", "minimum": 1, "maximum": 100, "type": "integer", "description": "Maximum number of entity records to return in batch mode (default 10).", "default": 10 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```