Copy page

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 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.

• 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:

Code
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.

Loading your governments…

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:

   Code
   {
     "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 18 or newer.

Claude Code (CLI)

Add the server with two --header flags:

Code
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 [email protected] — 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:

Code
{
  "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:

Code
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 [email protected] — we're happy to help you get connected.