GovCon API

MCP tool reference & install

Every install path, and all 53 tools with what each one does. For the philosophy behind why this exists, and how the tools group by GovCon lifecycle stage, see the MCP overview.

Install for your client

Same install command everywhere; only the config path changes per client. Python 3.10+ required.

Step 1: install the binary (all clients)

# If you don't have pipx: brew install pipx (macOS) or pip install --user pipx
pipx install govconapi-mcp

Installs to ~/.local/bin/govconapi-mcp, outside sandboxed folders like Documents.

Step 2: get an API key

14-day free trial at govconapi.com (no credit card). After trial: $19/mo Developer plan or $79/mo Pro. MCP is included with any paid plan.

Step 3: add to your client config

› Claude Desktop

Edit the config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "govconapi": {
      "command": "govconapi-mcp",
      "env": {
        "GOVCONAPI_KEY": "gca_your_key_here"
      }
    }
  }
}

Quit and reopen Claude Desktop. The govconapi tools appear in the tool picker.

› Claude Code (CLI)

One command adds it for your user:

claude mcp add govconapi govconapi-mcp -e GOVCONAPI_KEY=gca_your_key

Or edit ~/.claude/settings.json manually using the same JSON as Claude Desktop.

› Cursor

Settings > Cursor Settings > MCP > Add new MCP server.

Or edit ~/.cursor/mcp.json directly:

{
  "mcpServers": {
    "govconapi": {
      "command": "govconapi-mcp",
      "env": { "GOVCONAPI_KEY": "gca_your_key" }
    }
  }
}
› VS Code (with Continue extension)

Install Continue in VS Code, then edit ~/.continue/config.yaml:

mcpServers:
  - name: govconapi
    command: govconapi-mcp
    env:
      GOVCONAPI_KEY: gca_your_key
› Zed

Assistant panel > MCP Servers > Add Context Server. Or edit ~/.config/zed/settings.json:

{
  "context_servers": {
    "govconapi": {
      "command": "govconapi-mcp",
      "env": { "GOVCONAPI_KEY": "gca_your_key" }
    }
  }
}
› Custom Python agent (Anthropic SDK, LangChain, LlamaIndex)

Spawn the MCP server as a subprocess using the official mcp client SDK:

# pip install mcp
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

params = StdioServerParameters(
    command="govconapi-mcp",
    env={"GOVCONAPI_KEY": "gca_your_key"}
)

async with stdio_client(params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()
        result = await session.call_tool(
            "search_opportunities",
            {"naics": "541330", "limit": 10}
        )

Works with any LangChain / LlamaIndex / custom agent that supports MCP tool adapters.

How it works

The govconapi-mcp package is a thin Python wrapper around our REST API, organized by GovCon lifecycle stage rather than by internal API module. Your AI client spawns it as a local subprocess over stdio. The subprocess reads GOVCONAPI_KEY from its environment, proxies each tool call to https://govconapi.com/api/v1/... over HTTPS, and returns structured JSON, the same shape you'd get calling the REST API directly.

Because it wraps the REST API, everything else carries over automatically: your rate limits, plan restrictions, filter validation, and request logging. Usage shows up in your normal account dashboard.

Open source on PyPI under MIT. Audit it, fork it, run it locally with your own API key.

All 53 tools

Grouped by lifecycle stage, with every parameter, its type, and whether it's required. Expand a tool for its full signature.

13 tools are badged Pro: they return a 402 on the Developer plan. 4 more work on Developer but note where specific fields or filters are Pro-only. The other 36 have no plan distinction.

Market Research (12 tools)

› find_naics_codes Discover NAICS codes by federal spending and small-business set-aside leverage
sector: str, optional
prefix: str, optional
min_market: float, optional
max_competitors: int, optional
set_aside_family: str, optional
keywords: str, optional
sort_by: str, default 'market'
sort_order: str, default 'desc'
limit: int, default 50
offset: int, default 0
› get_naics_leaderboard Browse curated, ranked NAICS market leaderboards
board: str, required
limit: int, default 30
› get_naics_market One NAICS code's market profile: spending, competition, top buyers and incumbents
code: str, required
› get_naics_positioning A NAICS code's solicitation-side language and set-aside makeup
code: str, required
› get_naics_simplified_acquisition Award-value breakdown for a NAICS code over the last 12 months
code: str, required
› get_naics_competition How contested a NAICS market is: offers per award, single-bidder share
code: str, required
› discover_offices Which contracting offices buy a NAICS code, ranked by win-facts
naics: str, required
sort: str, default 'biggest'
limit: int, default 25
› get_office_profile One contracting office's full buying profile across every NAICS
office_code: str, required
› list_organizations Search the federal agency organization tree
type: str, optional
cgac: str, optional
parent_id: int, optional
hierarchy_level: int, optional
is_active: bool, optional
search: str, optional
limit: int, default 50
offset: int, default 0
› get_organization One federal organization's full record, with parent and children
organization_id: int, required
› get_org_relationships An organization's immediate children or ancestor chain
organization_id: int, required
direction: str, default 'children'
› search_forecasts Agency procurement forecasts, the only forward-looking layer in this API (incumbent_award block + direct contact fields are Pro-only)
source: str, optional
agency: str, optional
naics: str, optional
set_aside: str, optional
state: str, optional
est_award_fy: int, optional
est_award_quarter: str, optional
amount_min: float, optional
amount_max: float, optional
status: str, optional
is_recompete: bool, optional
keywords: str, optional
active_only: bool, default True
sort_by: str, optional
sort_order: str, optional
limit: int, default 100
offset: int, default 0

Opportunity Discovery (4 tools)

› search_opportunities Search federal contract opportunities (SAM.gov) with 15+ filters
naics: str, optional
psc: str, optional
naics_multiple: str, optional
agency: str, optional
keywords: str, optional
state: str, optional
set_aside: str, optional
notice_type: str, optional
posted_after: str, optional
due_before: str, optional
due_after: str, optional
date_from: str, optional
date_to: str, optional
value_min: float, optional
value_max: float, optional
has_attachments: bool, optional
sort_by: str, optional
sort_order: str, optional
limit: int, default 20
offset: int, default 0
› get_opportunity Fetch one opportunity's full record by notice_id
notice_id: str, required
› recent_changes Incremental sync of opportunities added or updated since a timestamp
since: str, required
limit: int, default 100
offset: int, default 0
› lookup_agency Resolve an agency acronym or partial name to the canonical SAM.gov string
query: str, required

Capture & Teaming (12 tools)

› search_companies Pro Search companies that have won at least one federal award
q: str, optional
naics: str, optional
agency: str, optional
naics_small: str, optional
limit: int, default 20
offset: int, default 0
› get_company_profile Pro One company's aggregate profile: SAM registration plus award totals
uei: str, required
› get_company_awards Pro Full paginated award history for one company
uei: str, required
limit: int, default 50
offset: int, default 0
sort_by: str, optional
sort_order: str, default 'desc'
› get_company_peers Pro Companies similar to this one by NAICS and agency overlap
uei: str, required
limit: int, default 10
› search_entities Search all SAM-registered entities, won an award or not (naics/state/business_type/naics_small filters are Pro-only, q alone works on any plan)
q: str, optional
naics: str, optional
state: str, optional
business_type: str, optional
active_only: bool, default False
naics_small: str, optional
limit: int, default 20
offset: int, default 0
› get_entities_expiring Pro SAM registrations expiring within N days
within_days: int, default 60
state: str, optional
naics: str, optional
limit: int, default 50
offset: int, default 0
› get_entity One SAM entity's full registration record, by UEI or CAGE code
uei: str, optional
cage_code: str, optional
› search_partners Pro Find teaming and partner firms by real past performance
naics: str, optional
agency: str, optional
state: str, optional
set_aside: str, optional
psc: str, optional
keywords: str, optional
limit: int, default 20
offset: int, default 0
› get_company_contact Pro Resolve a vendor's real decision-maker contact
uei: str, required
› search_contacts Pro Look up a contracting officer's contact info, the buyer side
name: str, optional
agency: str, optional
state: str, optional
email: str, optional
› search_recompetes Pro Contracts entering recompete within a chosen window
naics: str, optional
agency: str, optional
set_aside: str, optional
state: str, optional
amount_min: float, optional
amount_max: float, optional
ends_after_months: int, default 0
ends_within_months: int, default 18
date_anchor: str, default 'current_end'
options_exhausted_only: bool, default False
incumbent_excluded: bool, optional
sort_by: str, default 'ends_soonest'
limit: int, default 50
offset: int, default 0
› get_recompete Pro One recompeting contract by PIID, plus incumbent-vulnerability signals
piid: str, required

Bid & Proposal / Negotiate (10 tools)

› get_price_benchmark Percentile distribution of comparable contract value for a NAICS
naics: str, required
set_aside: str, optional
psc: str, optional
pricing_type: str, optional
agency: str, optional
value_basis: str, default 'current'
date_from: str, optional
date_to: str, optional
› get_price_position Where your specific bid value sits against real comparables
naics: str, required
value: str, required
set_aside: str, optional
psc: str, optional
pricing_type: str, optional
agency: str, optional
value_basis: str, default 'current'
sample_limit: int, default 10
date_from: str, optional
date_to: str, optional
› get_labor_rate_benchmark Awarded labor-rate benchmark for a labor category, from GSA CALC
labor_category: str, required
match: str, default 'contains'
education_level: str, optional
min_experience: int, optional
max_experience: int, optional
naics: str, optional
vendor: str, optional
worksite: str, optional
business_size: str, optional
security_clearance: str, optional
value_basis: str, default 'current'
sample_limit: int, default 10
› search_wage_determinations Search Davis-Bacon (DBA), Service Contract Act (SCA), and CBA wage determinations
type: str, optional
state: str, optional
county: str, optional
wd_number: str, optional
active_only: bool, default False
date_from: str, optional
date_to: str, optional
construction_type: str, optional
sort_by: str, optional
sort_order: str, optional
limit: int, default 25
offset: int, default 0
› get_wds_by_location Which wage determinations apply in a given state and county
state: str, required
county: str, optional
type: str, optional
limit: int, default 25
offset: int, default 0
› get_wage_rates Prevailing-wage rates across wage determinations, by occupation
classification: str, optional
type: str, optional
occupation_code: str, optional
wd_number: str, optional
state: str, optional
active_only: bool, default False
sort_by: str, optional
sort_order: str, optional
limit: int, default 25
offset: int, default 0
› get_wage_rate_summary The labor-cost floor for one occupation, aggregated across wage determinations
occupation_code: str, optional
classification: str, optional
type: str, default 'SCA'
state: str, optional
› get_wage_determination One wage determination's full record: locations and classification rates
wd_id: str, required
› get_vendor_risk_report Pro A 7-signal vendor risk report for one UEI
uei: str, required
› check_exclusion Check the SAM.gov exclusions list for debarred or suspended entities, before you bid (extra detail fields are Pro-only)
name: str, optional
uei: str, optional
cage_code: str, optional
limit: int, default 10

Award & Compliance (15 tools)

› search_contracts Search FPDS prime contract transactions, the comprehensive award record
uei: str, optional
parent_uei: str, optional
piid: str, optional
parent_piid: str, optional
agency: str, optional
naics: str, optional
award_type_code: str, optional
date_from: str, optional
date_to: str, optional
amount_min: float, optional
amount_max: float, optional
sort_by: str, optional
sort_order: str, optional
limit: int, default 50
offset: int, default 0
› get_contract One contract's latest transaction plus its obligation and value roll-up (the subaward_rollup block is Pro-only)
piid: str, required
› get_contract_modifications Every transaction row for a contract, the full modification trail
piid: str, required
limit: int, default 100
offset: int, default 0
› get_contract_vehicle The vehicle (IDIQ, GWAC, FSS, or BPA) an order was placed against
piid: str, required
› search_vehicles Search contract vehicles: IDIQs, GWACs, FSS schedules, BPAs, BOAs
uei: str, optional
parent_uei: str, optional
piid: str, optional
agency: str, optional
naics: str, optional
idv_type: str, optional
active_only: bool, optional
date_from: str, optional
date_to: str, optional
ceiling_min: float, optional
ceiling_max: float, optional
sort_by: str, optional
sort_order: str, optional
limit: int, default 50
offset: int, default 0
› get_vehicle One vehicle's detail: ceiling, period, and what's been ordered through it
piid: str, required
› get_vehicle_holders Pro Who holds a vehicle and who's actually earning through it
piid: str, required
limit: int, default 50
› search_subawards Search FFATA subawards: who primes paid as subcontractors
prime_uei: str, optional
sub_uei: str, optional
piid: str, optional
agency: str, optional
naics: str, optional
sub_name: str, optional
date_from: str, optional
date_to: str, optional
amount_min: float, optional
amount_max: float, optional
sort_by: str, optional
sort_order: str, optional
limit: int, default 50
offset: int, default 0
› get_subaward One FFATA subaward report by its SAM report ID
subaward_sam_report_id: str, required
› get_prime_subawards Every subaward a company paid out as a prime
uei: str, required
date_from: str, optional
date_to: str, optional
limit: int, default 50
offset: int, default 0
› get_prime_relationships Every prime that has paid this company as a subcontractor
uei: str, required
date_from: str, optional
date_to: str, optional
limit: int, default 50
offset: int, default 0
› search_protests Search GAO bid protests: who protested, on what, and the outcome
outcome: str, optional
agency: str, optional
status: str, optional
case_type: str, optional
filed_from: str, optional
filed_to: str, optional
case_number: str, optional
protester: str, optional
search: str, optional
sort: str, default 'recent'
limit: int, default 25
offset: int, default 0
› get_protests_on_solicitation Pro Every protest filed on one solicitation
solicitation_number: str, required
› search_awards Search SAM Award Notices, a sparse, self-reported slice, distinct from search_contracts
awardee: str, optional
uei: str, optional
naics: str, optional
agency: str, optional
value_min: float, optional
value_max: float, optional
date_from: str, optional
date_to: str, optional
limit: int, default 20
offset: int, default 0
› resolve_identifier Resolve between legacy DUNS and current UEI
identifier: str, required

FAQ

Common questions. If something isn't here, email [email protected].

Is MCP an extra paid tier?

No. MCP access itself is included with the Developer ($19/mo) and Pro ($79/mo) plans, same API key, same rate limits, and the 14-day free trial includes it too. What differs by plan is which of the 53 tools you can call, not access to MCP itself, see the next question.

Which tools need Pro?

13 of 53, badged Pro in the table above, return a 402 on Developer: the Companies cluster, Teaming Partners, Contacts, Vendor Risk, Recompete Watchlist, vehicle holders, and per-solicitation protest detail. 4 more work on Developer, with a note under each naming exactly which fields or filters are Pro-only. The other 36 have no plan distinction.

How many tools does it expose?

53, spanning Market Research, Opportunity Discovery, Capture & Teaming, Bid & Proposal/Negotiate, and Award & Compliance. See the table above.

Does this work with Cursor, VS Code, Claude Code, Zed, Windsurf?

Yes, all of them. MCP is an open standard, any client that speaks it works identically. See the install section above for each client's config file path.

How does rate-limiting work?

Each tool call from your AI counts as one API call against your plan's limits, same as the REST API. The current per-plan limits are on the pricing page. You won't hit them with normal interactive use.

What data does it expose?

SAM.gov opportunities and exclusions, FPDS/USAspending prime contracts and subawards, GSA wage determinations and labor rates, SBA DSBS small-business certifications, and the federal agency organization tree. All 53 tools proxy the same REST API this site runs on, so coverage matches it exactly.

My MCP server fails to start on macOS

Most common cause: the binary is inside a sandboxed folder (~/Documents). Claude Desktop can't spawn processes from there. Use pipx install govconapi-mcp instead of a manual venv, it puts the binary at ~/.local/bin/ which sandboxes can reach. Check the log at ~/Library/Logs/Claude/mcp-server-govconapi.log for details.

Is my API key safe?

The key lives in your local client's config file. It's sent over HTTPS in the Authorization header on each call. The MCP server never logs, transmits, or exposes it anywhere else. Source code is public and auditable on PyPI.

Can the tools be chained into a workflow?

Yes. Query parameters like uei, naics, and piid work the same way across most tools, and each tool's docstring states exactly which of its response fields feed into which other tool's parameters. See the composability section on the overview page.

What's MCP anyway?

Model Context Protocol, an open standard from Anthropic that lets AI assistants call external tools. Think of it as “the API protocol for AI”. When you install an MCP server, your AI gains new capabilities. Ours gives it 53, spanning the federal contracting lifecycle.

How do I report a bug or request a tool?

Email [email protected]. The MCP server is open source, PRs welcome. We ship updates fast because it's a thin wrapper over the REST API.

Try it

Grab a 14-day trial key (no credit card), paste one JSON block into your Claude / Cursor / VS Code config, and ask your assistant a question about federal contracts. The same key works for the REST API too.

Get an API key • Jump to install • Why we built this • See pricing