MCP server setup and tool reference

Updated October 8, 2026

GovCon API's MCP server lets an AI assistant answer federal contracting questions from the same data, on the same plan, as the REST API: you ask in plain words, and the assistant picks the tools and carries IDs from one call into the next. Connect Claude with no install, or run the server locally in Claude Code, Cursor and other MCP clients; when the REST API fits better is on MCP.

Connect Claude, no install

Claude on the web, in the desktop app and on mobile connects to our hosted MCP server at https://mcp.govconapi.com/mcp (the bare https://mcp.govconapi.com works too). Nothing runs on your machine and there is no key to paste: you sign in with the email your GovCon API key was sent to, or with a new email to start a free trial.

1. In Claude, open Customize, then Connectors, and add a custom connector with that address. This link opens the dialog with the name and address filled in.
2. Select Connect. Our sign-in page opens and names the app you are connecting, claude.ai.
3. Enter your email, then the 6-digit code we send to it. An email we have not seen before starts a free trial, and the key is emailed to you too.
4. Ask Claude a federal contracting question. Each of the six tools has example questions below.

The connector answers with your plan and limits, the same as your key on the REST API. Tools that need Pro answer a trial or Developer account with the upgrade message, and after you upgrade the same connection uses the new plan without reconnecting. A local install is tied to the key itself: upgrading emails you a new key, which replaces the old one in GOVCONAPI_KEY. On Claude Team and Enterprise, an organization owner adds the connector in organization settings first; each member then connects with their own email.

Connect ChatGPT, no install

ChatGPT on the web connects to the same hosted server, added as a custom MCP server. There is nothing to install and no key to paste. ChatGPT has no link that fills the details in, so you paste the address once.

1. Open ChatGPT Plugins, select +, then Add custom MCP server.
2. Name it GovCon API and enter the server URL https://mcp.govconapi.com/mcp.
3. Set authentication to OAuth, accept ChatGPT's warning about custom servers, and select Create as a plugin.
4. Our sign-in page opens and names the app you are connecting, chatgpt.com. Enter your email, then the 6-digit code we send to it. An email we have not seen before starts a free trial.
5. Ask ChatGPT a federal contracting question. The six tools are the same as in Claude.

Plans, limits and upgrades work exactly as with the Claude connector above. On ChatGPT Business and Enterprise, workspace settings decide whether members can add custom MCP servers.

Install locally

For Claude Code, Cursor, VS Code, Zed, Claude Desktop's config file and your own agents, the package govconapi-mcp runs on your machine and calls the API with your key.

1. Install the package

Requires Python 3.10 or later.

pipx install govconapi-mcp

No pipx? On macOS run brew install pipx, then pipx ensurepath; elsewhere run python3 -m pip install --user pipx, then python3 -m pipx ensurepath. pipx puts the govconapi-mcp command where Claude Desktop and other clients can start it.

If you use uv, you can run the server with uvx --from govconapi-mcp govconapi-mcp instead of installing it with pipx.

2. Get a GovCon API key

The server takes your normal GovCon API key, and a free trial key works. Get a free key; prices, limits and the trial are on Pricing.

3. Add it to your client

Every client starts the same command, govconapi-mcp, and passes your key in the GOVCONAPI_KEY environment variable. The server offers the six tools by default; to get the 53 single-purpose tools instead, add GOVCONAPI_TOOLS set to all next to the key.

Claude Desktop

Claude Desktop also takes the connector, with nothing to install. Use the config file when you want the server running on your machine, or the 53 single-purpose tools.

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 its tool list.

Claude Code

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

--scope user makes the server available in every project. Leave it out to add it to the current project only.

Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "govconapi": {
      "command": "govconapi-mcp",
      "env": { "GOVCONAPI_KEY": "gca_your_key" }
    }
  }
}

VS Code, with the Continue extension

Install Continue, then add to ~/.continue/config.yaml:

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

Zed

Edit ~/.config/zed/settings.json:

{
  "context_servers": {
    "govconapi": {
      "command": "govconapi-mcp",
      "env": { "GOVCONAPI_KEY": "gca_your_key" }
    }
  }
}

Your own agent (Python)

Start the server as a subprocess with the official mcp client library:

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

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

async def main():
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool(
                "search",
                {"dataset": "opportunities", "filters": {"naics": "541330"}, "limit": 10},
            )
            print(result.content[0].text)

asyncio.run(main())

4. Ask it something

Ask your client a question the tools answer, such as "Find contract opportunities for NAICS 541512 posted in the last 30 days" or "Which contracts in NAICS 541330 are coming up for recompete?" The second needs a Pro key. If a call fails, the fix is under Troubleshooting.

The six tools

Six tools, each named for a job, reach every dataset and record in the API. A model picks the right one more reliably from six than from fifty, and their definitions take about a sixth of the context. A typical question runs resolve, then search, then get: a name becomes the ID or code the filters take, the search returns records with their IDs, and get reads one in full.

Your client reads each tool's parameters from the server when it connects, and a filter a dataset does not take is refused with the list of the ones it does. The Plan notes below are explained under Plans.

resolve

Turns what you said into the IDs and codes the other tools take. Every kind works on every plan.

Kind	From	To
agency	An agency name or acronym, such as "Navy" or "FEMA"	The exact agency value the search filters match
naics	Words from NAICS titles, such as "computer" or "engineering"	Matching NAICS codes, with each market's size. It matches titles, not topics: for cybersecurity, try "computer".
company	A company name	Its SAM registrations, with their UEIs. A large firm has several.
identifier	A legacy 9-digit DUNS number	The matching UEI and company
organization	An agency or sub-agency name	Its ID in the federal hierarchy

Ask it: "Which NAICS codes cover engineering services, and how big is each market?" or "What is the UEI for the company we are teaming with?"

search

Searches one of 17 datasets with that dataset's own filters, 20 rows at a time by default, paged with an offset. Dates are YYYY-MM-DD.

Dataset	Plan	What it searches
opportunities		SAM.gov contract opportunities by NAICS, PSC, agency, keywords, state, set-aside, notice type, dates and value.
opportunity_changes		Notices added or changed since a time you give.
forecasts	Pro fields	Work agencies plan to buy and have not posted yet, from GSA, DHS and HHS.
award_notices		SAM.gov award notices, the self-reported subset of federal awards.
contracts		FPDS prime contract awards by NAICS, agency, UEI, PIID, award type, date and amount, and the orders placed under a vehicle.
vehicles		IDIQs, GWACs, GSA schedules, BPAs and BOAs, by holder, PIID, agency, NAICS or type.
subawards		Which primes paid which subcontractors, from FFATA subaward reports.
recompetes	Pro	Contracts entering recompete within a window you choose, with option runway and incumbent facts.
companies	Pro	Firms with award history, by name. To rank firms without a name, use partners.
entities		Every SAM registration, by name, NAICS, state, business type or SBA small-business status for a NAICS.
expiring_registrations	Pro	SAM registrations that expire within the number of days you choose.
partners	Pro	Firms ranked by dollars won (FY2025 onward) in a NAICS, agency, state, PSC or socioeconomic category: who wins the work, the incumbents, teaming candidates.
protests		GAO bid protests by agency, protester, status, outcome and filing date.
exclusions		Debarred and suspended parties, by name, UEI or CAGE code.
wage_determinations		Service Contract Act, Davis-Bacon and CBA wage determinations.
wage_determinations_by_location		The wage determinations in force in a state or county.
offices		The contracting offices that buy a NAICS code, ranked.

Ask it: "Find small-business set-aside solicitations from the Navy in NAICS 541330 due in the next 60 days" or "Which Army contracts in NAICS 541512 come up for recompete in the next 18 months?" The second needs Pro.

get

Reads one record in full by its ID. The ID comes from a search result or from resolve; a UEI opens the most, from the SAM registration to the company's award history, its competitors, a vendor risk report and the subawards it paid or received.

The ID you have	Record kinds
Notice ID	opportunity: the full notice, with description, contacts and attachments
PIID	contract (Pro fields), contract_modifications, contract_vehicle (the vehicle it was ordered under), recompete (Pro)
Vehicle PIID	vehicle, vehicle_holders (Pro)
UEI	entity (Pro fields), company_profile (Pro), company_awards (Pro), company_peers (Pro), vendor_risk (Pro), prime_subawards, prime_relationships
CAGE code	entity (Pro fields)
Solicitation number	protests_on_solicitation (Pro)
Subaward report ID	subaward
Wage determination ID	wage_determination
Office code	office
Organization ID	organization, organization_relationships (its children or its ancestors)

Ask it: "What has this company won, and who does it compete against?" or "Is anyone protesting this solicitation, and when is the decision due?" Both need Pro.

market

Reads a NAICS market. Every view works on every plan.

View	What it answers
size	Obligated dollars, award count and concentration for one NAICS code
competition	Offers per award, single-bidder share and the set-aside mix
solicitation_language	The wording contracting officers use in that market's notices
small_buys	How much is bought under the micro-purchase and simplified-acquisition thresholds
leaderboard	Ranked NAICS codes: biggest, least crowded or most open
find_codes	NAICS codes by market size, number of competitors and set-aside share

Ask it: "How big is NAICS 541512, and how contested is it?" or "Which IT services codes have a large market and few competitors?"

price

Price evidence for a bid.

Kind	Plan	What it answers
benchmark	Pro	The distribution of comparable contract values for a NAICS code, by pricing type, agency or set-aside
position	Pro	Where a contract or bid value ranks against comparable contracts
labor_rates	Any paid plan	Awarded GSA Schedule ceiling rates for a labor category, by education and experience
wage_rates		Service Contract Act or Davis-Bacon hourly rates for an occupation
wage_summary		The spread of those rates for one occupation

Ask it: "Where would a $2.2 million firm-fixed-price bid rank against comparable contracts in NAICS 541330?" (Pro) or "What is the Davis-Bacon wage for an electrician in Maryland?"

contact

Finds who to talk to. Both kinds need Pro.

Kind	What it finds
company_decision_maker	A company's decision-maker, from its UEI, with third-party SAM registration agents filtered out
contracting_officer	A contracting officer's details, from a name or an email, narrowed by agency and state. A lookup, not a directory.

Ask it: "Who is the decision-maker at the firm that holds this contract?" or "How do I reach the contracting officer named on this notice?"

How it works

Every way in runs the same six tools from the same open-source package, and every tool call becomes a GovCon API request made with your key.

• Locally, your client starts govconapi-mcp as a process and talks to it over stdio. The process reads GOVCONAPI_KEY from its environment and sends each call to https://govconapi.com over HTTPS, with the key in the Authorization header.
• Through the hosted server (Claude or ChatGPT), the same code runs on our server. Signing in ties the connection to the email on your account, and each call uses that account's current key, so a new key or a new plan applies without reconnecting.

Neither keeps a copy of the data. Your plan's access, your request limits and the API's parameter validation apply to every call, so a rejected value comes back with the API's own error message. Tool filters use the REST API's parameter names, though tool defaults such as page size can differ; what each parameter accepts and every response field are in the API guide and /openapi.json.

The package is MIT licensed, with its source at github.com/govconapi/govconapi-mcp and its releases at pypi.org/project/govconapi-mcp.

Plans

There is no MCP plan: any GovCon API key works, including a free trial key, and each tool call is one request on it, under your plan's limits. The six tools call the 53 below, so a dataset or record reached through the six keeps the plan of the tool behind it. What each note in a Plan column means:

• Pro: a free trial or Developer key gets the API's upgrade message (HTTP 402) instead of data.
• Pro fields: works on every plan, with some fields filled only for a Pro key.
• Any paid plan: a free trial key gets the upgrade message.
• No note: works the same on every plan, within the free trial's limits.

Which plan includes each capability, with prices, limits and the trial, is in the comparison table on Pricing.

The 53 single-purpose tools

The six call these. Each does one job and is named for it, and a local install serves them instead of the six when GOVCONAPI_TOOLS is set to all, for agents and prompts that call tools by name. The Claude connector serves the six. They are grouped by the job in front of you, not by our API routes.

Market research

Tool	Plan	What it does
find_naics_codes		Find NAICS codes by federal spending, number of winning firms and set-aside share, when you do not yet know which code to look at.
get_naics_leaderboard		Ranked NAICS markets from a fixed set of named leaderboards.
get_naics_market		One NAICS market: spending, competition, set-aside share, top buyers and top incumbents.
get_naics_positioning		The solicitation side of a NAICS market: the wording contracting officers use in notices, set-aside share and top soliciting agencies.
get_naics_simplified_acquisition		Award counts by value band for a NAICS code, and the offices making simplified-acquisition awards.
get_naics_competition		How contested a NAICS market is: offers per award, single-bidder share, award trend, and the dollar share won by firms holding each set-aside certification.
discover_offices		The contracting offices that buy a NAICS code, ranked, with each office's spending, competition and set-aside share.
get_office_profile		One contracting office's buying profile across every NAICS it buys.
list_organizations		Search the federal organization tree by name, type, CGAC code or parent.
get_organization		One federal organization with its parent, children and ancestor chain.
get_org_relationships		Only an organization's children, or only its ancestor chain.
search_forecasts	Pro fields	Agency procurement forecasts: work an agency plans to buy and has not posted yet. A Pro key also gets incumbent_award and the direct contact emails and phones.

Opportunity discovery

Tool	Plan	What it does
search_opportunities		Search SAM.gov contract opportunities by NAICS, PSC, agency, keywords, state, set-aside, notice type, dates, value and whether a notice has attachments.
get_opportunity		One opportunity's full record, with description, contacts and attachments, by notice ID.
recent_changes		Opportunities added or updated since a timestamp, for incremental sync.
lookup_agency		Resolve an agency acronym or partial name to the SAM.gov agency name that most agency filters match.

Capture and teaming

Tool	Plan	What it does
search_companies	Pro	Search companies by name across SAM.gov award notices and FPDS prime contracts; registered firms with no awards also match.
get_company_profile	Pro	One company by UEI: its SAM registration combined with award totals.
get_company_awards	Pro	One company's award history, award by award.
get_company_peers	Pro	Companies that compete where this one does, by NAICS and agency overlap.
search_entities		Search every SAM-registered entity, with or without awards, by name, NAICS, state, business type, active status or SBA small-business status for a NAICS.
get_entities_expiring	Pro	SAM registrations that expire within the number of days you choose.
get_entity	Pro fields	One SAM registration record, by UEI or CAGE code. A Pro key also gets subaward revenue, top paying primes, and FPDS contract totals and dates; by UEI, also sba_profile.
search_partners	Pro	Teaming partners with past performance matching a NAICS, agency, place-of-performance state, socioeconomic category, PSC or keywords.
get_company_contact	Pro	A company's decision-maker contact, with third-party SAM registration agents filtered out.
search_contacts	Pro	A contracting officer's contact details, looked up by name or email. A lookup, not a directory.
search_recompetes	Pro	Contracts entering recompete within a window you choose, with option runway and incumbent facts.
get_recompete	Pro	One recompeting contract by PIID, with certification-lapse, lone-holder and single-agency-dependence signals on the incumbent.

Bid and pricing

Tool	Plan	What it does
get_price_benchmark	Pro	The distribution of comparable contract values for a NAICS code, by pricing type.
get_price_position	Pro	Where a contract or bid value ranks against comparable contracts, with the nearest ones.
get_labor_rate_benchmark	Any paid plan	Awarded GSA Schedule labor rates for a labor category: hourly percentiles, out-year escalation and sample rates.
search_wage_determinations		Search Davis-Bacon, Service Contract Act and CBA wage determinations by type, state, county, number or revision date.
get_wds_by_location		The wage determinations in force in a state or county.
get_wage_rates		Prevailing wage rates for an occupation across wage determinations.
get_wage_rate_summary		The wage floor for one occupation across wage determinations: hourly percentiles and health and welfare fringe.
get_wage_determination		One wage determination: its locations and every classification's wage and fringe.
get_vendor_risk_report	Pro	Public-record risk signals for one UEI, a triage summary, and the vendor's contract and subaward exposure.
check_exclusion		Search the SAM.gov exclusions list by name, UEI or CAGE code.

Award and compliance

Tool	Plan	What it does
search_contracts		Search FPDS prime contract transactions by UEI, PIID, agency, NAICS, award type, action date and amount.
get_contract	Pro fields	One contract's latest transaction and its totals across every modification. A Pro key also gets subaward_rollup.
get_contract_modifications		Every transaction on a contract, oldest first.
get_contract_vehicle		The vehicle (IDIQ, GWAC, FSS schedule or BPA) an order was placed against.
search_vehicles		Search contract vehicles: IDIQs, GWACs, FSS schedules, BPAs and BOAs.
get_vehicle		One vehicle: ceiling, period and a summary of the orders placed through it.
get_vehicle_holders	Pro	Who holds a vehicle, and who has been paid through it.
search_subawards		Search FFATA subaward reports: which primes paid which subcontractors.
get_subaward		One subaward report, by its SAM report ID.
get_prime_subawards		Every subaward a company paid out as a prime.
get_prime_relationships		Every prime that paid a company as a subcontractor.
search_protests		Search GAO bid protests by protester, agency, outcome, status, case number or filing date.
get_protests_on_solicitation	Pro	Every GAO protest on one solicitation, whether any is open or sustained, and the nearest decision deadline.
search_awards		Search SAM.gov award notices, the self-reported subset of federal awards. For the full award record, use search_contracts.
resolve_identifier		Resolve a legacy DUNS to its UEI, or a UEI to its DUNS. A miss is inconclusive: the crosswalk is built from subaward filings.

Troubleshooting

Claude connector

The sign-in code does not arrive. Check your spam folder. On the code page, the link to send a new code also lets you use a different email. A code expires after 10 minutes, and five wrong entries end it; either way, request a new one.

"Too many codes requested." Wait 15 minutes, then request a code again.

"This sign-in link expired." Go back to Claude and select Connect on GovCon API again.

"Can't connect this account." The free trial on that email has ended, or its subscription is cancelled. The page links to Pricing; after you subscribe, connect again with the same email.

Claude is using a trial when you have a paid plan. You signed in with an email other than the one your key was sent to, and a new email starts its own trial. Disconnect GovCon API in Claude's connector settings and connect again with your account's email.

Calls stop working, or Claude asks you to connect again. Select Connect on GovCon API in Claude's connector settings and sign in with the same email. Your key and plan stay as they are.

There is no option to add a custom connector. On Claude Team and Enterprise, an organization owner adds GovCon API in organization settings first.

Local install

The client cannot start the server. Install with pipx (step 1), not into a virtual environment inside Documents or another protected folder. If the client still cannot find govconapi-mcp, put the full path from which govconapi-mcp (macOS, Linux) or where govconapi-mcp (Windows) in command. On macOS, Claude Desktop logs the server's output to ~/Library/Logs/Claude/mcp-server-govconapi.log.

Every call says "GOVCONAPI_KEY environment variable is not set". The tools list without a key, but calls need one. Add the key to the server's env block and restart the client.

"Invalid API key". Keys start with gca_. A trial key that has ended also reads as invalid. To check the key outside the client, call /api/v1/me, which returns its plan and remaining requests:

curl -H "Authorization: Bearer gca_your_key" https://govconapi.com/api/v1/me

Your prompts call tools such as search_opportunities by name, and the client cannot find them. The server offers the six by default. Add GOVCONAPI_TOOLS set to all next to the key for the 53 single-purpose tools.

Either way

A tool answers "requires the Pro plan", "requires a paid plan" or "trial has expired". The message is the API's own: what you asked for is marked Pro or Any paid plan on this page, or the trial has ended. Which plan includes it is on Pricing.

"Rate limit exceeded". Each tool call is an API request on your key, and the key has reached its request limit, its short per-minute limit, or a per-endpoint burst limit. One question can make several calls. /api/v1/me shows what remains; limits by plan are on Pricing.

Where does my API key go? Locally, it stays in your client's config and the server's environment; the server sends it only to govconapi.com and does not write it to disk. With the Claude connector, Claude never holds your key: it holds a sign-in token, and our server looks up your account's key for each call. Either way, only the tool's parameters reach us, never the conversation around them. What the API logs about each request is in the Privacy Policy.

Does it work in other MCP clients? The local package runs in any MCP client that can start a local server and pass it an environment variable.

Found a bug, or need a tool? Email [email protected], or open an issue at github.com/govconapi/govconapi-mcp.

Start using it

Connect Claude with your email, or get a free key and add it to your client, then ask a federal contracts question.