# Connect an AI assistant The Govinity API has a built-in **MCP (Model Context Protocol) server**, so you can point an AI assistant straight at a government's public record. Every read endpoint in the [API Reference](/api) becomes a tool the assistant can use — meetings, agendas, legislation, documents, video, and more. ## What you need Every connection needs three things: - **Your API key.** The MCP server uses the _same_ key as the REST API. If you don't have one yet, see [Get Access](/get-access). - **A government code** — the city or county you want to query, for example `city-of-springfield`. Your key is authorized for a specific set of codes. - **The MCP endpoint URL** for the environment you're using: | Environment | MCP endpoint | | ----------- | -------------------------------------------- | | Production | `https://api.govinity.com/mcp` | | Staging | `https://api.staging.govinity.io/mcp` | | Integration | `https://api.integration.govinity.io/mcp` | The API key and government code travel as two connection headers: ``` Authorization: Bearer YOUR_API_KEY X-Govinity-Government-Code: city-of-springfield ``` > Each connection is scoped to **one government**. A connection set up for a single > city sets the code once — the people using it never have to choose. ## Cursor & VS Code — one click Sign in above, pick a government, and click a button. The connector installs itself, already set up with your API key — nothing to copy or configure. > The install buttons contain your API key, so treat them like a password — don't > share a button link or paste it anywhere public. ## Claude Desktop Claude Desktop connects through a small bridge called **`mcp-remote`**, which lets it talk to a remote server and send your API key. (Claude's built-in custom connectors use a browser sign-in flow instead, which the Govinity server doesn't offer yet — so use the steps below to connect with your key today.) 1. In Claude Desktop, open **Settings → Developer → Edit Config**. This opens `claude_desktop_config.json` in your editor. (You can also open the file directly: `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, or `%APPDATA%\Claude\claude_desktop_config.json` on Windows.) 2. Add this entry, replacing the key and government code with your own: ```json { "mcpServers": { "govinity": { "command": "npx", "args": [ "-y", "mcp-remote", "https://api.govinity.com/mcp", "--header", "Authorization:${GOVINITY_AUTH}", "--header", "X-Govinity-Government-Code:city-of-springfield" ], "env": { "GOVINITY_AUTH": "Bearer YOUR_API_KEY" } } } } ``` 3. Save the file and fully quit and reopen Claude Desktop. The Govinity tools then appear behind the attachment icon in a chat. > The key sits in the `env` block (and the header uses `Authorization:${GOVINITY_AUTH}` > with no space) on purpose — it sidesteps a known spaces-in-arguments bug on > Windows. `npx` installs `mcp-remote` automatically; it needs > [Node.js](https://nodejs.org) 18 or newer. ## Claude Code (CLI) Add the server with two `--header` flags: ```bash claude mcp add --transport http govinity https://api.govinity.com/mcp \ --header "Authorization: Bearer YOUR_API_KEY" \ --header "X-Govinity-Government-Code: city-of-springfield" ``` Then type `/mcp` inside Claude Code to see the Govinity tools. ## ChatGPT ChatGPT's custom connectors (Developer Mode) only authenticate through a browser **OAuth** sign-in — they can't send an API key header, and there's no bridge like `mcp-remote` for the web app. We can add OAuth to the Govinity MCP server, and plan to; until then, ChatGPT can't connect with an API key. If ChatGPT support matters to you, tell us at [support@govinity.com](mailto:support@govinity.com) — it helps us prioritize. In the meantime, **Claude Desktop**, **Cursor**, or **VS Code** connect today with your key. ## Other AI tools Any tool that supports a **remote (HTTP) MCP server** can connect. Point it at the endpoint and add the two headers: - **Endpoint:** `https://api.govinity.com/mcp` - **Headers:** `Authorization: Bearer YOUR_API_KEY` and `X-Govinity-Government-Code: city-of-springfield` Many tools (Cursor, Windsurf, and others) use an `mcp.json`-style config: ```json { "mcpServers": { "govinity": { "url": "https://api.govinity.com/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY", "X-Govinity-Government-Code": "city-of-springfield" } } } } ``` Tools that only launch local (stdio) servers — like the Claude Desktop setup above — use the `mcp-remote` bridge instead, passing the same two values as `--header` flags. To check the endpoint without any tool, send a test request: ```bash curl -i -X POST https://api.govinity.com/mcp \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "X-Govinity-Government-Code: city-of-springfield" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":"1","method":"tools/list"}' ``` A `200` response with a list of tools means you're connected. ## Check it works Ask your assistant to **"confirm which government you're connected to."** It should reply with the city or county from your connection. Then try "what meetings are coming up?" or "summarize the last city council meeting." ## Troubleshooting | Message | What it means | | ------------------------------------ | ---------------------------------------------------------------------------------------- | | `401 Unauthorized` | The API key is missing or wrong. Check it and the `Bearer ` prefix. | | `403 government-not-authorized` | Your key isn't allowed to access that government. Use one it covers, or contact support. | | `government-code-required` | The connection is missing the `X-Govinity-Government-Code` header. | | Tools don't appear in Claude Desktop | Check the JSON for a missing comma or bracket, then fully restart the app. | ## Need help? Reach us at [support@govinity.com](mailto:support@govinity.com) — we're happy to help you get connected.