# Set up GovChime MCP

You are configuring an AI client to use GovChime's remote Model Context
Protocol (MCP) server. Follow the section for the client you are running in.
If you are not one of the clients listed below, tell the user their client is
not supported yet and stop — do not improvise a configuration.

## What this connects to

| Item | Value |
| --- | --- |
| Endpoint | `https://mcp.govchime.com/mcp` |
| Transport | Remote Streamable HTTP |
| Authorization | OAuth 2.1, authorization code with required S256 PKCE |
| Scope | `govdata.read` |
| Access | Read-only |

The server is in beta: tool coverage and client support may change. Use the
endpoint above exactly as written and do not substitute another hostname.

There is no API key to paste and no secret to store. The user authorizes their
own GovChime account in a browser, and the client receives a short-lived,
audience-bound, read-only token. If you are asked to put a credential in a
config file, you are following the wrong instructions.

## Codex CLI — verified

```bash
codex mcp remove govchime
codex mcp add govchime \
  --url https://mcp.govchime.com/mcp \
  --oauth-client-id govchime-mcp-codex
codex mcp login govchime
```

Do **not** pass `--oauth-resource`. Codex derives the resource from
protected-resource metadata, and supplying it as well sends `resource` twice.

`codex mcp login` opens a browser. The user signs in with their normal
GovChime account and approves the connection.

Verify:

```bash
codex mcp list
curl -fsS https://mcp.govchime.com/health/mcp
```

## Claude (claude.ai custom connector) — supported

Hosted clients cannot use a loopback callback, so they use a separate public
client whose redirect allowlist contains only Claude's exact callback URLs.

Direct the user to **Customize → Connectors → + → Add custom connector**:

| Field | Value |
| --- | --- |
| URL | `https://mcp.govchime.com/mcp` |
| OAuth Client ID | `govchime-mcp-web` |
| OAuth Client Secret | leave blank — this is a public client |

This is a UI flow. You cannot complete it on the user's behalf; give them the
three values and stop.

## Claude Code — supported

```bash
claude mcp add --transport http govchime https://mcp.govchime.com/mcp
```

Then run `/mcp` inside Claude Code and authenticate when prompted.

## Cursor, ChatGPT, GitHub Copilot — not enabled

Their OAuth callback and token-lifecycle requirements have not been reviewed
against this server. Tell the user the client is documented but not enabled,
and point them at https://www.govchime.com/mcp/configure. Do not attempt a
configuration.

## What the user can ask once connected

Federal procurement questions in plain language — open solicitations by
industry, agency, or set-aside; who won a contract and how much was obligated;
who the incumbent on a recompete is; how spending in a market has moved.

Two things to carry into your answers, because they are the errors this data
invites:

- An **opportunity** is work the government announced it intends to buy. An
  **award** is a contract it actually signed. They are different records; an
  opportunity marked awarded is a notice, not the contract.
- An award's dollar figure is a **cumulative running total** carried on every
  transaction of that award. Never add those figures across awards to get a
  period total — use the spending aggregate tools, which sum per-transaction
  obligations.

## If setup fails

```bash
curl -fsS https://mcp.govchime.com/health/mcp
curl -fsS https://mcp.govchime.com/.well-known/oauth-protected-resource/mcp
```

A failing health check is a server-side problem, not a client misconfiguration.
If the token expired, re-run the client's login command. Full reference:
https://www.govchime.com/mcp/configure