New:Introducing Socket Scanning for VS Code Marketplace Extensions.Learn more →
Get Started

matchawards-mcp

Package Overview
Dependencies
Maintainers
1
Versions
10
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

matchawards-mcp

MCP server for MatchAwards: search US government contracts, grants and jobs from matchawards.com.

pipPyPI
Version
1.1.2
Weekly downloads
86
-79.23%
Maintainers
1
Weekly downloads
 
Created

MatchAwards MCP server

MatchAwards gives AI agents direct access to continuously updated government and business contracts, grants, jobs, awards and collaboration opportunities.

This is the Model Context Protocol server for MatchAwards. It lets Claude, Cursor, VS Code and other MCP clients search US government contract opportunities, grants and jobs, and past contract and grant awards. It only reads data, and it needs no account and no API key.

Tools

ToolWhat it returnsExample prompt
search_contractsFederal and state contract opportunities. Filters: NAICS (up to 10 codes), state, keyword, set-aside, federal or state only, posted within N days, open only, agency (by name), 1 to 50 results, paging."Find open roofing contracts in Virginia posted in the last week."
search_grantsFederal grant and funding opportunities. Filters: NAICS, keyword, posted within N days, open only, 1 to 50 results, paging (grant notices carry no state)."Are there open broadband grants?"
search_jobsJob postings from the last 30 days. Filters: NAICS, state, keyword, posted within N days, 1 to 50 results, paging."Show electrician jobs in Texas from the last 7 days."
get_opportunityThe full record of one opportunity: the search row plus its description, published points of contact (name and title) and, where MatchAwards has them, AI-generated notes (ai: fit, reasoning, subcontracting and large-prime angles, summary), labelled as AI-generated."Who do I contact about the second result?"
lookup_naicsNAICS codes from words ("cybersecurity") or from a 2 to 6 digit code prefix, with each code's page on matchawards.com. 1 to 25 codes."What NAICS code covers cybersecurity consulting?"
search_awardsPast federal contract awards and grant awards: awardee (name, UEI, DUNS), amount, date, agency, NAICS, set-aside, place, solicitation, contract and CFDA numbers, links to matchawards.com and to SAM.gov or USAspending. Filters: type, NAICS, agency (by name), state, awardee name, UEI, keyword, awarded within N days (up to 1,095), 1 to 50 results, paging."Who won VA contracts under NAICS 541512 in the last year?"
get_companyOne firm's award history by UEI: names, location (city, state, country), contract and grant totals, first and last award dates, top NAICS codes and agencies, the 10 most recent awards. No contact details."Show the award history of UEI C3KXNLTAAY98."
assess_opportunityA qualification brief on one opportunity: days left (US Eastern), open or closed, set-aside and NAICS (and whether they match the user's my_set_aside and my_naics), the AI-generated notes, the 5 newest similar awards (same NAICS at the same agency, or all agencies when that agency has none; the newest 150 at most from the last 3 years, and sample says which dates were read and whether that was all of them), the top 5 firms that won similar work (by count, then total), the quartiles of their award amounts and a coverage note."Should we bid on the first result? We're NAICS 336413, small business."
find_teaming_partnersUp to 10 firms that won similar awards, from the newest records read (sample; same NAICS in the opportunity's state, then at its agency; the NAICS anywhere when neither returns any and award requests are left), de-duplicated by UEI, ranked by count, then the most recent, then the total, each with a why line written from the records. Firms without a UEI in the records are listed with uei: null, and the note says their history can't be looked up. role (sub, prime, any) puts smaller or larger typical awards first among firms with the same count. Public award data only: no contacts, no profile links."Who could we team with on that Air Force notice?"

The agency filter takes a name. The server looks it up among MatchAwards' agencies (exact name first, then names that start with it, then the rest in the API's order) and filters by the best match only, for now; the result's note names that agency and lists up to three other matches (one department can have several agency accounts), and when nothing matches, the search covers all agencies and the note says so. Lookups are cached for 10 minutes.

Award records may be incomplete (federal awards especially), so every award result says so. The two brief tools describe firms as having won similar work, never as the incumbent; they make at most 1 opportunity request and 6 award requests per call (at most 3 per query, shared by the queries), within 6 seconds, and when either limit cuts the lookup short they answer with what they read and a warning. Their sample says how many award records the figures rest on, their dates, and whether every matching record was read. A grant award's title is its recipient's name, so the model is asked to head it with the awardee name and CFDA number instead.

Every tool is read-only and needs no account (except my_matches, a hosted tool that exists only with account linking on; see Linked accounts): each declares readOnlyHint, idempotentHint, a title and securitySchemes: [{"type": "noauth"}] (in _meta). Results are structured: each tool publishes an outputSchema and returns structuredContent, with the same JSON as text for clients that read only text. Every result carries a url on matchawards.com (and a sam_url for federal notices), and the server asks the model to show them as markdown links. Links to matchawards.com carry utm_source, utm_medium and utm_campaign parameters naming the AI host the request came from (for example utm_source=chatgpt); links to other sites are left unchanged.

Changes in 1.1.2

  • No NAICS codes given: the instructions have the model ask what the user's business does (or its codes) and find the codes with lookup_naics, in every mode. With linking on, my_matches on a profile without codes asks the same, searches with the codes found (keeping the profile's state and set-aside) and offers the match-settings link to save them.
  • "Nothing here needs an account" is in the instructions only with linking off; with linking on it contradicted my_matches.
  • The keyword hint says keyword search matches whole words in titles, and to try another form of the word.

Changes in 1.1.1

  • Hosted server: MATCHAWARDS_API_MAX_IN_FLIGHT (default 16) caps the requests to the public API in flight at once for the whole server. A request waits up to 5 seconds for a free slot (less when the tool's own time limit is nearer), then the tool answers "busy, retry" without calling the API. The per-minute API budget is spent only once a slot is held.

Changes in 1.1.0

  • Tool choice: assess_opportunity is described as the tool for fit, bid/no-bid and bid-brief questions, and get_opportunity points those questions to it (contracts and grants only).
  • Keyword hint: a contract, grant or award search by keyword with no NAICS code and only a few rows says in its note that keyword search matches titles only and points to lookup_naics.
  • Hosted server metrics: tool calls by User-Agent family, rows returned per list tool, MatchAwards API timing per endpoint and outcome, API requests per tool call, distinct ChatGPT conversations and first-seen ChatGPT users. Stats show the empty-result rate per tool; the ledger gains a rows column, added at open.
  • Hosted server: optional account linking and the my_matches tool (see Linked accounts). Off unless MATCHAWARDS_AUTH_ISSUER is set; with it off nothing else changes.

Changes in 1.0.4

  • The result card renders in Claude: its _meta.ui.domain is left out for Claude, which accepts only its own sandbox domain; other hosts still get https://matchawards.com.

Changes in 1.0.3

  • Hosted server: usage-stat rows are kept 180 days by default (was 365), set by MATCHAWARDS_USAGE_RETENTION_DAYS.

Changes in 1.0.2

  • Cards come from a new tool, show_results, which the model calls once with the ids it picked; the search tools return data only. The card (results-v2.html) expands a row in place and has an "Ask about this" button.
  • Results filtered by naics say which requested codes matched: matched_naics (the record's own codes) and, on contract notices, ai_matched_naics (codes MatchAwards' AI suggested).
  • Links to matchawards.com carry UTM parameters naming the AI host.
  • Hosted server: the shared limit is 1200 requests per minute, and /metrics adds tool latency, distinct-caller and client counts.

Changes in 1.0

  • search_by_naics is removed: search_contracts, search_grants and search_jobs take the same naics filter on its own.
  • find_contacts is removed: get_opportunity returns the published contacts with the rest of the record.
  • Results are structured output (outputSchema plus structuredContent). Fields the API adds later appear in results only once the schema declares them. get_opportunity returns ai (AI-generated notes, labelled as such) where MatchAwards has them, else null.
  • Tool annotations are closed-world (openWorldHint: false): the tools read the MatchAwards catalog only.
  • New tools: lookup_naics, search_awards, get_company, assess_opportunity and find_teaming_partners; search_contracts takes an agency name.

Cards

Hosts that render MCP Apps (ChatGPT, Claude) get one inline card per answer: after searching, the model calls show_results with up to 10 contract or grant ids it picked, and the card lists up to 8 of them with title, agency, place, a federal/state/grant badge, the deadline (days left, closed, or no fixed deadline), set-aside and NAICS code. Ids it could not show (not found, a job, or not fetched because MatchAwards was busy) are counted under the list. The search tools return data only, with no card. Clicking a row expands it (posted date, solicitation, office, NAICS, set-aside); its "Ask about this" button asks the model for that opportunity's details, and its "Open on MatchAwards" link opens its page. The card is one self-contained HTML resource, ui://matchawards/results-v2.html (text/html;profile=mcp-app): no scripts or styles from elsewhere and no network requests, so its CSP allows nothing. It renders only the tool's structuredContent, and never calls a tool itself.

The other tools return their structured results without a card.

Cards are off by default. Set MATCHAWARDS_WIDGETS=1 to list the resource and show_results, which points at it (_meta.ui.resourceUri); the other tools' results are the same either way. tests/widget_harness/ holds a minimal host page with sample results for checking the card in a browser.

Hosted

A hosted endpoint runs at https://matchawards.com/mcp. Add it as a remote MCP server (connector) by URL, with nothing to install and no key:

  • ChatGPT: add a custom connector with the URL https://matchawards.com/mcp.
  • Claude (claude.ai or Claude Desktop): Settings, Connectors, add a custom connector with the same URL. Claude Code: claude mcp add --transport http matchawards https://matchawards.com/mcp.
  • Cursor: in mcp.json, {"mcpServers": {"matchawards": {"url": "https://matchawards.com/mcp"}}}.

The hosted endpoint serves the same tools. It is limited per client address (IPv6: per /64) to 30 requests per minute and 10 per 5 seconds, per IPv6 /48 to 120 per minute, and to 1200 per minute for all clients together (ChatGPT's shared pool: 600); over a limit it answers HTTP 429 with Retry-After.

Install

The server runs with uvx, which comes with uv.

Claude Desktop

Add this to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json), then restart Claude Desktop:

{
  "mcpServers": {
    "matchawards": {
      "command": "uvx",
      "args": ["matchawards-mcp"]
    }
  }
}

Claude Code

claude mcp add matchawards -- uvx matchawards-mcp

Cursor

Add this to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "matchawards": {
      "command": "uvx",
      "args": ["matchawards-mcp"]
    }
  }
}

VS Code

Add this to .vscode/mcp.json in your workspace:

{
  "servers": {
    "matchawards": {
      "type": "stdio",
      "command": "uvx",
      "args": ["matchawards-mcp"]
    }
  }
}

Other clients

Any MCP client that can start a stdio server works. The command is uvx matchawards-mcp.

OpenClaw

integrations/openclaw-plugin holds a native OpenClaw plugin (@matchawards/openclaw-plugin on ClawHub) whose nine tools call the hosted endpoint, and a ClawHub skill, matchawards, that teaches an agent the public REST API with curl. Both are read-only and need no account. The plugin's tools.json is generated from this server's tool list (integrations/openclaw-plugin/scripts/gen_tools.py), and the test suite fails when it is out of date.

Run the HTTP server yourself

matchawards-mcp --http serves the same tools over stateless Streamable HTTP (JSON replies, no sessions, no SSE) at http://127.0.0.1:8765/mcp:

uvx matchawards-mcp --http
curl -s http://127.0.0.1:8765/mcp -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' -H 'MCP-Protocol-Version: 2025-06-18' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

How requests are handled, in order:

  • Repeated and trailing slashes are folded, so /mcp/ and //mcp count as /mcp. Any path other than /mcp and /healthz gets 404 (with account linking on, /.well-known/oauth-protected-resource and /.well-known/oauth-protected-resource/mcp serve the protected-resource metadata, like /healthz on any host and not rate-limited).
  • GET /healthz returns ok and is not rate-limited.
  • A Host header not in MATCHAWARDS_ALLOWED_HOSTS (or 127.0.0.1, localhost) gets 421, whatever the method.
  • Only POST /mcp is served. GET, DELETE and OPTIONS get 405 (no SSE stream, no sessions, no CORS).
  • A POST needs Content-Length (411 without it), and bodies over 64 KB get 413.
  • Rate limit per client (per ChatGPT user from OpenAI's addresses), then the server-wide cap: 429 with Retry-After.
  • With account linking on, a tools/call of a tool that needs a linked account, without a usable token, gets 401 (403 when the token lacks the scope) with WWW-Authenticate; ChatGPT gets the same challenge as a tool result. Nothing else is checked.

The client is the socket address, or the X-Real-IP header when the socket address is in MATCHAWARDS_TRUSTED_PROXIES (IPv6 is keyed per /64; all /64s inside one /48 also share MATCHAWARDS_RATE_PER_PREFIX_MIN). Run it behind a reverse proxy that sets X-Real-IP, and do not expose the port directly. The limits are kept in memory per process. A bad value in any of the variables below stops the server at startup. The log has one line per request (method, path, status, duration, a hashed client key), never headers or bodies.

ChatGPT calls come from OpenAI's shared egress addresses (published list, bundled with the package and refreshed daily; a failed refresh keeps the last good list), so one address carries many users and a per-IP limit would throttle them together. From those addresses only, a request is limited per x-openai-subject (ChatGPT's per-user id, kept only as a keyed hash) and all ChatGPT traffic shares MATCHAWARDS_EGRESS_PER_MIN; a request without the header counts in that pool only. The header from any other address is ignored, and the User-Agent is never used.

In Docker, nginx on the host reaches the container from the compose network's gateway, not from loopback, so name that address exactly. Read it with docker network inspect <network> --format '{{(index .IPAM.Config 0).Gateway}}' and set, for example:

MATCHAWARDS_HTTP_HOST=0.0.0.0
MATCHAWARDS_TRUSTED_PROXIES=127.0.0.1/32,::1/128,172.18.0.1/32

Do not trust a broad private range such as 172.16.0.0/12: it may overlap your internal network, and any host in it could then pick its own rate-limit key.

Configuration

VariableDefaultPurpose
MATCHAWARDS_API_BASEhttps://matchawards.comAPI base URL. Change it only for development.
MATCHAWARDS_HTTP_HOST127.0.0.1--http only: address to listen on.
MATCHAWARDS_HTTP_PORT8765--http only: port to listen on.
MATCHAWARDS_RATE_PER_MIN30--http only: requests per minute per client.
MATCHAWARDS_RATE_BURST10--http only: requests per 5 seconds per client.
MATCHAWARDS_RATE_PER_PREFIX_MIN120--http only: requests per minute for all IPv6 /64s inside one /48 together.
MATCHAWARDS_GLOBAL_PER_MIN1200--http only: requests per minute for all clients together. Must be above MATCHAWARDS_EGRESS_PER_MIN (otherwise the server will not start).
MATCHAWARDS_RATE_PER_SUBJECT_MIN30--http only: requests per minute per ChatGPT user (x-openai-subject, from OpenAI's egress addresses only).
MATCHAWARDS_RATE_SUBJECT_BURST10--http only: requests per 5 seconds per ChatGPT user.
MATCHAWARDS_EGRESS_PER_MIN600--http only: requests per minute for all ChatGPT traffic together.
MATCHAWARDS_GLOBAL_API_PER_MIN900--http only: API calls per minute for the whole server (one search can make up to 3). Over it, a tool answers "MatchAwards is busy, retry in N seconds" without calling the API.
MATCHAWARDS_API_MAX_IN_FLIGHT16--http only: requests to the public API in flight at once for the whole server (the linked-account profile check is not counted). Slow searches each hold a database connection on the API side, so this, more than the per-minute budget, bounds the load. A request waits up to 5 seconds for a free slot (less when the tool's own time limit is nearer); past that the tool answers "MatchAwards is busy, retry in 5 seconds" without calling the API or spending MATCHAWARDS_GLOBAL_API_PER_MIN.
MATCHAWARDS_TRUSTED_PROXIES127.0.0.1/32,::1/128--http only: proxies (CIDRs, comma-separated) whose X-Real-IP header is trusted. Loopback only by default.
MATCHAWARDS_ALLOWED_HOSTSmatchawards.com,staging.matchawards.com--http only: accepted Host headers, comma-separated (127.0.0.1 and localhost are always accepted).
MATCHAWARDS_USAGE_DB/data/usage.db--http only: SQLite file for the usage stats. If its directory is missing or not writable, the server logs one warning and records nothing.
MATCHAWARDS_USAGE_SALTunset--http only: secret for the ChatGPT caller fingerprint. Unset: no fingerprint is stored.
MATCHAWARDS_METRICS_TOKENunset--http only: Bearer token for /metrics. Unset: the metrics listener does not start.
MATCHAWARDS_METRICS_HOST127.0.0.1--http only: address of the metrics listener.
MATCHAWARDS_METRICS_PORT9765--http only: port of the metrics listener.
MATCHAWARDS_USAGE_RETENTION_DAYS180--http only: days usage-stat rows are kept.
MATCHAWARDS_AUTH_ISSUERunset--http only: the OAuth authorization server, an https URL (http only on localhost, 127.0.0.1 or [::1], for a local run; e.g. https://matchawards.com). Set: account linking is on. Unset: no linking, and nothing else changes.
MATCHAWARDS_RESOURCE<issuer>/mcp--http only, linking on: this server's public https URL (http only on a loopback host), the resource tokens are issued for.
MATCHAWARDS_AGENT_API_BASEMATCHAWARDS_API_BASE--http only, linking on: base URL of the account API that checks a linked user's token.
MATCHAWARDS_WIDGETSunset1: serve the result card (see Cards). Unset: no card resource and no show_results.

Linked accounts

Hosted mode (--http) only, and off unless MATCHAWARDS_AUTH_ISSUER is set. Off, the tool list, the instructions and every result are the same as without it.

On, a user can link their MatchAwards account (sign in with Google or email on matchawards.com) and gets one more tool, my_matches: open contracts matching the NAICS codes and state on their MatchAwards profile, with the rows, paging and links of search_contracts (type narrows to federal or state, ignore_state drops the state filter, which skips federal notices without a state). Notices open to all firms are included; only_my_set_aside keeps only those set aside for the profile's set-aside (federal notices only: a state-only search never takes a set-aside), and otherwise the note names it so the model can point out the set-aside ones. profile_used says which filters came from the profile (the set-aside's code and name). The search takes the first 10 NAICS codes on the profile, and the note says so when it has more. A profile without NAICS codes gets no search, and a settings_url to its match settings instead; its note asks the model to ask the user what their business does, find the codes with lookup_naics, search with them and offer the link to save them. Every other tool still needs no account and never reads a token.

  • matchawards.com is the OAuth authorization server; this server is only the resource server, and serves its protected-resource metadata (RFC 9728) at /.well-known/oauth-protected-resource/mcp. The only scope is profile:read. my_matches declares securitySchemes [{"type": "noauth"}, {"type": "oauth2", "scopes": ["profile:read"]}]; every other tool keeps noauth only.
  • A tools/call of my_matches without a usable token gets a challenge naming the metadata and the scope. Claude and other MCP clients get HTTP 401 (403 when the token lacks profile:read) with WWW-Authenticate, before the tool runs, and start linking on it. ChatGPT (User-Agent openai-mcp) links on a tool result instead, so it gets a 200 result with isError and the same header value in _meta["mcp/www_authenticate"]. When MatchAwards does not answer the token check, the call fails with a "busy, retry" error, and when it refuses the account itself (a disabled or suspended account, or a token of an app that is not an agent app) with a plain error: neither is a challenge, since linking again would not help.
  • The token check is one GET {MATCHAWARDS_AGENT_API_BASE}/api/agent/v1/me with the token. Only a token issued for this server (MATCHAWARDS_RESOURCE, RFC 8707) is taken (scheme and host compared case-insensitively, the path exactly), and not one whose token_expires_at has passed. From the answer only the account's opaque id (sub), its NAICS codes, set-aside, state, UEI, organization name and match-settings link (only an https link on matchawards.com) are read. The answer is kept in memory for 60 seconds (a rejected token for 30), under a keyed hash of the token.
  • What is kept: the ledger's linked flag on each tool call (whether it ran with a linked account), and in memory a salted hash of the account's sub for the distinct-account gauge. Tokens, the Authorization header and account ids are never stored or logged.

Usage stats (hosted mode)

With --http the server keeps usage stats in a SQLite file (MATCHAWARDS_USAGE_DB, WAL mode). stdio mode records nothing. Writes run on two background threads and are best-effort: a failed write is counted in mcp_ledger_errors_total and never fails a request. Rows older than MATCHAWARDS_USAGE_RETENTION_DAYS days (default 180) are deleted, at most once a day.

What is recorded:

  • Tool calls: one row per call that reached a tool: time, tool name, outcome (ok, invalid_input, upstream_error, bad_response (a reply the tools cannot read), upstream_timeout (the API ran out of time; retry), partial (assess_opportunity or find_teaming_partners answered, but its request or time limit cut the award lookup short), rate_limited_upstream, busy, internal_error, link_required (my_matches answered with the linking challenge), forbidden (my_matches for an account MatchAwards refuses)), whether it ran with a linked account (linked, 0 or 1; never which account), the rows a list-returning tool answered with (rows: search_contracts, search_grants, search_jobs, search_awards, lookup_naics, find_teaming_partners (firms), show_results (ids shown) and my_matches, on an ok or partial call; NULL for other tools and other outcomes; added to an older ledger at open), the client network (IPv4 /24 or IPv6 /48), the User-Agent (first 200 characters), its family (openai-mcp, claude-user, claude, cursor, ..., prober or other) and the latency. Calls stopped by the rate limit are counted in a metric, with no row. Arguments the SDK rejects before the tool runs leave no row either; they still count in the transport table as tools/call.
  • Transport, per day: one counter per client network, JSON-RPC method (known MCP methods only, anything else is _other) and clientInfo name and version, with the last User-Agent seen. clientInfo is read from the first 8 KiB of an initialize body, or from params._meta (2026-07-28 clients), as the body streams past; the body is not buffered. At most 50 counters per client network and day; past that they fold into _other.
  • ChatGPT callers: when MATCHAWARDS_USAGE_SALT is set and a request from ChatGPT's egress addresses carries x-openai-subject (ChatGPT's anonymous per-user id; from any other address it is ignored), the tool-call row stores a 16-hex HMAC-SHA256 of it, to count distinct ChatGPT callers (openai-mcp family only in the stats). x-openai-session changes per conversation, so it is never written to the ledger; it only feeds the in-memory chatgpt_session gauge (see Metrics), under the same conditions as x-openai-subject.

Never recorded: tool arguments (search terms, ids), request or response bodies, full client addresses, raw header values, tokens and account ids.

Read the stats with:

matchawards-mcp stats --days 7          # --db PATH to read another file

It prints tool calls per tool and outcome, calls per family, real calls vs probers vs our own tests (matchawards-test/ UA), distinct client networks (probers and own tests left out), distinct ChatGPT fingerprints, tool calls with a linked account, the empty-result rate per list-returning tool (rows = 0 over calls with rows set), transport requests per method and the top clientInfo names. In Docker: docker exec <container> matchawards-mcp stats --days 1.

Metrics

When MATCHAWARDS_METRICS_TOKEN is set, a second listener in the same process (MATCHAWARDS_METRICS_HOST:MATCHAWARDS_METRICS_PORT, default 127.0.0.1:9765) serves GET /metrics in the Prometheus text format, with Authorization: Bearer <token> (401 without it). The /mcp port never serves /metrics (404): it trusts X-Real-IP from the proxy, so publish only the metrics port to the network Prometheus scrapes from. All metrics are in memory and reset on restart; every label value comes from a fixed set, never a client address, subject or argument.

  • mcp_tool_calls_total{tool,outcome,family} (counter): tool calls (the ledger writes one row for each), by User-Agent family (the ledger's fixed set: openai-mcp, claude-user, claude, cursor, ..., prober or other; never the raw User-Agent).
  • mcp_tool_duration_seconds{tool} (histogram, buckets 0.1 0.25 0.5 1 2.5 5 10 20 30 s): tool call latency, for the same calls.
  • mcp_tool_result_rows{tool} (histogram, buckets 0 1 5 10 25 50): rows a list-returning tool answered with, once per ok or partial call (the ledger's rows).
  • mcp_tool_api_pages{tool} (histogram, buckets 0 1 2 3 5): MatchAwards API requests one tool call made: search pages (the cursor followed while filling limit), the agency-name lookup (not when cached), the detail and award lookups of the composite tools, show_results' fetches. 0 when the server-wide API budget answered busy before any request.
  • mcp_api_duration_seconds{endpoint,outcome} (histogram, the buckets of mcp_tool_duration_seconds): latency of every MatchAwards API request, to tell API time from the rest of a tool call. endpoint: search (opportunity search), awards, opportunity (one record), company, naics, agencies, me (the account-linking profile check) or other; outcome: ok (an answer below HTTP 400), client_error (any other 4xx: a rejected parameter, an unknown id, a 401 or 403 from the profile check, a 429), error (5xx, or no connection), or timeout (no answer within 10 s, the API's own timeout answer, or cut off by a tool's time limit). A request cancelled for any other reason (the client went away, shutdown) is not recorded.
  • mcp_requests_total{method} (counter): requests served on /mcp by JSON-RPC method.
  • mcp_rejected_total{reason} (counter): rate_limit_client, rate_limit_prefix, rate_limit_subject, rate_limit_egress, rate_limit_global, size, host, path, method.
  • mcp_agent_requests_total{family} (counter): requests served by User-Agent family.
  • mcp_clients_total{client} (counter): initialize requests by clientInfo.name, folded into chatgpt, claude, cursor, vscode, n8n, matchawards, mcp-inspector, other or unknown.
  • mcp_distinct_callers{kind,window} (gauge, window = 1h or 24h): distinct client networks (/24 or /48, probers and own tests left out) distinct ChatGPT users (chatgpt_subject: x-openai-subject on requests from ChatGPT's egress addresses only), distinct ChatGPT conversations (chatgpt_session: x-openai-session, accepted exactly as x-openai-subject is; in memory only, never in the ledger) and distinct linked accounts (account, listed only with account linking on). Kept as per-process salted hashes, at most 100,000 per kind. The distinct-caller gauges reset on restart, so a 24h value is only complete 24 hours after a start.
  • mcp_distinct_evictions_total{kind} (counter): distinct-caller keys dropped to stay under that cap (non-zero only under a flood of new networks or subjects). While it is above zero the distinct counts are a lower bound: a caller rotating subjects or networks can push others out.
  • mcp_ledger_errors_total (counter): usage ledger writes that failed.
  • mcp_chatgpt_subjects_new_total (counter): tool calls from a ChatGPT user whose fingerprint has no earlier row in the ledger (first seen within the retention window), checked by the ledger writer and counted once that write has committed. Needs MATCHAWARDS_USAGE_SALT, like the fingerprints; best-effort like other ledger writes (a failed write counts in mcp_ledger_errors_total, never in this).
  • mcp_link_challenges_total{host,error} (counter, listed only with account linking on): challenges sent, by host (chatgpt, claude, other) and error (invalid_token, insufficient_scope).
  • mcp_linked_calls_total{tool} (counter, listed only with account linking on): tool calls that ran with a linked account.

Ops notes

  • Mount a volume at /data (or set MATCHAWARDS_USAGE_DB) so the file survives a container rebuild.
  • For ChatGPT fingerprints, nginx must pass x-openai-subject through to the container (it does by default unless headers are cleared), and MATCHAWARDS_USAGE_SALT must be set and kept stable: a new salt starts new fingerprints.
  • For Docker, set MATCHAWARDS_METRICS_HOST=0.0.0.0 and publish the metrics port only on the internal network.

Data

The data is US federal and state contract opportunities, grants, jobs, federal contract awards and grant awards from matchawards.com. Only public posts are returned, and each result links back to its page on matchawards.com.

  • Contract and grant searches return open items by default: a response deadline of today or later, US Eastern. An item with no deadline counts as closed.
  • Job search covers the last 30 days.
  • Results come newest first. When has_more is true, the model can ask for the next page with cursor.
  • A keyword search (contracts, grants or awards) without naics whose first page is all there is (no cursor passed, no has_more, no warning) and holds fewer than 5 rows, and fewer than its limit, says in its note that the keyword matches titles only, and that lookup_naics gives the codes for a line of work.
  • A narrow filter (an agency, a rare name) can scan the newest records without a match while more exist further back; the result's warning then says so and gives the cursor to continue with.
  • If the first request of a search fails, the tool returns an error. If a later page fails, the tool returns the rows it already has, with a warning that says why it stopped.
  • A result row in an unexpected format is left out and counted in warning; the rest of the search is returned.
  • Each API call times out after 10 seconds.
  • The API is rate-limited per IP: 60 requests per minute, plus a burst limit of 20 requests per 5 seconds. One search call can use up to three requests when the filters are narrow and results are sparse, plus one to look up an agency name (cached for 10 minutes). When the limit is reached, the tool returns an error that tells the model how many seconds to wait.

Development

python -m venv .venv
.venv/bin/pip install -e ".[test]"
.venv/bin/pytest

The tests make no network calls.

tests/golden/prompts.json lists prompts with the tool a model should pick (or none), for manual checks of tool selection in a client.

License

MIT. See LICENSE.

Keywords

ai-agent

FAQs

Related posts