Tango MCP (AI agents)¶

The Tango MCP server gives AI agents access to federal procurement competitive intelligence via the Tango API. The server is hosted at https://govcon.dev/mcp and uses HTTP transport — you connect your MCP client to the remote endpoint; no local install required. Use it from Claude Desktop, Cursor, the OpenAI Responses API, or any MCP-compatible client.

What it does¶

The server exposes 5 tools that let an AI agent research government contracting data on your behalf:

• Discover what's in the data — Use resolve to find entities, agencies, vehicles, NAICS/PSC codes, contracts, opportunities, OTAs, OTIDVs, subawards, organizations, protests, and IT Dashboard investments by name or keyword; get identifiers and previews to use with other tools.
• Search awards and related data — Use search to query contracts, IDVs, vehicles, OTAs, OTIDVs, subawards, organizations, GSA eLibrary contracts, CALC labor rates (LCATs), bid protests, and IT Dashboard investments. Filter by vendor, agency, NAICS, PSC, dates, and many other criteria; optionally get aggregate statistics (obligated amounts, set-aside breakdown, etc.).
• Search active opportunities — Use search_opportunities to find SAM.gov opportunities and agency forecasts by agency, NAICS, set-aside type, response deadline, and keyword.
• Get full details for any item — Use get_details to retrieve detailed information for a specific entity, contract, IDV, vehicle, opportunity, OTA, OTIDV, organization, subaward, protest, MAS SIN, GSA eLibrary contract, or IT Dashboard investment by ID, with optional related-data enrichment.
• Read curated API documentation — Use fetch_api_docs to pull short, LLM-friendly documentation for any major Tango resource (contracts, opportunities, vehicles, IT Dashboard, etc.).

Quick start¶

Prerequisites¶

• A Tango API key (from the Tango web interface), or for OAuth clients: access tokens via Authorization: Bearer <access_token>
• An MCP-compatible client (e.g. Cursor, Claude Desktop)

Connect via HTTP¶

The server is hosted at https://govcon.dev. The MCP endpoint is https://govcon.dev/mcp. Configure your client to connect to this URL over HTTP and send your API key (see Using with MCP clients below).

Using with MCP clients¶

Remote MCP (HTTP) — recommended¶

Connect your client to the hosted server over HTTP using mcp-remote. The server expects your Tango API key in the X-Tango-API-Key header (or an OAuth bearer token in Authorization: Bearer).

Cursor / Claude with remote URL (API key):

{
  "mcpServers": {
    "tango-remote": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://govcon.dev/mcp",
        "--header",
        "X-Tango-API-Key: your_api_key_here"
      ]
    }
  }
}

Cursor / Claude with remote URL (OAuth bearer token):

{
  "mcpServers": {
    "tango-remote-oauth": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://govcon.dev/mcp",
        "--header",
        "Authorization: Bearer your_oauth_token_here"
      ]
    }
  }
}

Use a fresh access token from your Tango OAuth flow; refresh the token when it expires.

Streamable HTTP (JSON mode) — The server uses HTTP transport and returns JSON responses rather than Server-Sent Events (SSE). If you see errors like "Unexpected content type" or "Failed to open SSE stream", ensure the client uses JSON mode.

API key security — Prefer setting the API key via environment variable or a secrets manager. When using mcp-remote with --header X-Tango-API-Key: ..., avoid committing the key to config; use a local env var or secret so the key is not logged or stored in plain text.

Claude Desktop¶

If you have the Tango MCP Desktop Extension (.mcpb), install it in Claude Desktop (Settings → Extensions), set the Server URL to https://govcon.dev/mcp, and enter your Tango API key when prompted. The extension connects to the hosted server over HTTP — no local server required.

OAuth flow¶

When connecting over HTTP, you can authenticate with a bearer token instead of an API key. This is useful for clients that support OAuth (e.g. ChatGPT MCP) or when you obtain access tokens from Tango's OAuth server.

1. Obtain an access token from the Tango OAuth server at tango.makegov.com. Use the authorization code or client credentials flow; supported grant types include authorization_code, client_credentials, and refresh_token. Required scope is typically read.

2. Send the token on each request via the Authorization header: Authorization: Bearer <your_access_token>.

3. Auth precedence — The server resolves auth in this order: (1) Authorization: Bearer if present, (2) X-Tango-API-Key if present, (3) TANGO_API_KEY from the environment (stdio/local only).

OAuth discovery — The server exposes standard discovery endpoints so clients can find the Tango authorization server and required scopes:

• Authorization server metadata: GET /.well-known/oauth-authorization-server and GET /mcp/.well-known/oauth-authorization-server
• Protected resource metadata: GET /.well-known/oauth-protected-resource

These return JSON (issuer, authorization_endpoint, token_endpoint, scopes_supported, etc.). The default issuer is https://tango.makegov.com.

OpenAI Responses API¶

OpenAI's MCP integration requires a publicly accessible server. Use the hosted MCP endpoint https://govcon.dev/mcp in your tools configuration. See the OpenAI MCP documentation for details.

Available tools¶

Enrichment matrix (get_details(..., include_related=True))¶

Enrichment failures degrade gracefully — if a related-data fetch fails, the main object is still returned with empty related blocks.

Resources¶

The server also exposes static MCP resources. Clients that support resource fetching can pull curated reference content without a tool call:

Configuration¶

• API key vs OAuth: Send your Tango API key in the X-Tango-API-Key header, or use Authorization: Bearer <token> with an OAuth access token from tango.makegov.com.
• Endpoint: The hosted server is at https://govcon.dev; the MCP endpoint is https://govcon.dev/mcp (HTTP transport).
• Response format: The hosted server returns responses in TOON (Token-Oriented Object Notation) by default — a compact serialization that is roughly 30–60% smaller than JSON for typical responses. To force standard JSON, set TANGO_RESPONSE_FORMAT=json (relevant when self-hosting; the hosted server returns TOON).

Self-hosting / local environment variables¶

If you run the server locally (e.g. via stdio for development), the following environment variables are recognized:

Notable behaviors¶

The server includes several robustness features worth knowing about when integrating:

• Strict argument validation. Unknown tool arguments are rejected with a structured error that lists the valid arg names — no silent drops. Pass type not record_type, etc.
• Zero-result hints. When a search returns no results, the response includes a _hint with the active filters and broaden-query guidance — helpful for LLM agents that would otherwise guess randomly.
• Ordering-alias rewrite. LLM-friendly sort field names like expiring, date, value, and amount are rewritten to API-valid values (award_date, obligated, total_contract_value).
• Parameter coercion. Bare strings for array fields (naics_codes, psc_codes, set_aside_types) are wrapped automatically. active accepts "true" / "false". notice_type accepts both code letters (p, k, o, a, m, r, s, u, i, g) and full names ("Solicitation", "Sources Sought", etc.).
• Circuit breaker. After 3 transient upstream failures (502 / 503 / 504 / timeout) within 60 seconds, the server short-circuits with UpstreamUnavailableError. A probe is allowed every 10 seconds during the cooldown.
• Tier-aware errors. Tier-gated endpoints (e.g. CALC labor rates) return a typed error with an upgrade hint rather than a raw HTTP exception.

Troubleshooting¶

424 error from OpenAI — OpenAI can only reach publicly accessible servers. Use the hosted endpoint https://govcon.dev/mcp.

Empty results — Verify your API key is valid. Check that the UEI, NAICS code, or other identifiers you are using exist in the Tango database.

502 Bad Gateway / "Failed to open SSE stream" — The server uses HTTP transport and JSON responses, not SSE. If the client expects SSE, use a client that supports JSON mode.

403 when calling the server URL — A proxy or firewall may be blocking the request to https://govcon.dev/mcp. Ensure your client sends the API key or Bearer token as described above.

"Invalid API key or authentication required" — When connecting to https://govcon.dev/mcp, the server must receive either your Tango API key in the X-Tango-API-Key header or an OAuth bearer token in the Authorization: Bearer <token> header. Ensure your MCP client is configured to send one of these.

Get help¶

For API keys, account issues, or MCP connection problems:

• Email: [email protected]
• Tango web interface: tango.makegov.com — sign in to manage your account and API keys.

Privacy¶

Data handling and privacy are described in our Privacy policy.

References¶

• govcon.dev — Hosted Tango MCP server (HTTP transport)
• Model Context Protocol Specification
• MCP Inspector — Interactive testing and debugging for MCP servers
• OpenAI MCP Documentation
• Tango API