DevelopersAI assistantsHow to

Connecting the MCP server

Connect Claude Desktop, Claude Code or another MCP client to CapitolMath, and the tools it gives the assistant: two for every kind of record, and five analysis tools.

Applies toEditor license

The CapitolMath MCP server puts the same data as the REST API in front of an AI assistant — Claude Desktop, Claude Code or any other client that speaks the Model Context Protocol — as tools it can call for itself. Ask "Which Colorado housing bills are still in committee?" and the assistant searches, looks into the bills it finds, and answers from the record.

Every plan includes it, the free Browse plan too.

Before you start#

You need:

An API key with the Read the API permission — see Creating an API key. The server uses it for every call.
Node.js, to run the server.
The server itself, capitolmath-mcp. It isn't published to a package registry; if you don't have a copy, ask support@capitolmath.ai. Build it once in its folder:

npm install
npm run build

Connect Claude Desktop#

In Claude Desktop, open Settings → Developer and select Edit Config. It opens claude_desktop_config.json.

Add CapitolMath under mcpServers, with the full path to the server you built and your key:

{
  "mcpServers": {
    "capitolmath": {
      "command": "node",
      "args": ["/full/path/to/capitolmath-mcp/dist/index.js"],
      "env": {
        "CAPITOLMATH_API_KEY": "vd_live_…",
        "CAPITOLMATH_BASE_URL": "https://capitolmath.ai"
      }
    }
  }
}

Save the file and restart Claude Desktop. Claude can now use CapitolMath's tools.

Set CAPITOLMATH_BASE_URL as shown. Without it, the server looks for a CapitolMath running on your own computer and every call fails.

Other clients#

Any client that runs local (stdio) MCP servers takes the same three things: the command node, the path to dist/index.js, and the two environment variables. In Claude Code, for example:

claude mcp add capitolmath \
  -e CAPITOLMATH_API_KEY=vd_live_… -e CAPITOLMATH_BASE_URL=https://capitolmath.ai \
  -- node /full/path/to/capitolmath-mcp/dist/index.js

The server can also run over HTTP for a shared deployment (MCP_TRANSPORT=http, at /mcp, on port 3333 unless PORT says otherwise).

The tools#

Two tools search and read every kind of record; five more are analysis tools that compute rather than look something up.

Tool	What it does
`search_records`	Search one kind of record — bills, officials, committees, events or your tracked items — with that kind's filters, or run your organization's saved views by name
`get_record`	One record of any kind in full, by the `id` a search returned
`find_model_legislation`	Whether a bill's text appears near-identically in other states, and which came first
`get_whip_count`	A forecast of how a chamber would vote on a bill that hasn't had its floor vote
`get_legislator_votes`	A legislator's roll-call votes, joined to the bills
`compare_legislators`	Two to ten legislators side by side
`get_executive_signing_history`	Every bill a governor or the President signed, vetoed or let become law unsigned

The kinds of record#

Each call to search_records names a kind and passes that kind's filters. A filter that doesn't apply to the kind is refused, and the reply lists the ones that do.

Kind	What it is	Saved views it runs
`bill`	Bills and resolutions: outcome, furthest stage, topics, sponsors and, where they're live, effective dates, with your organization's tracking of each	Your bill views, from Legislation, and your Tracked items views (the bills they list)
`official`	Legislators, and the governor or President	Your legislator views, from Elected Officials
`committee`	A legislature's committees, with roster sizes and bill counts	None
`event`	The calendar: hearings, markups, floor sessions and session deadlines	Your calendar views, or your bill views to find the meetings their bills are on
`tracked_item`	Your organization's own work on a bill: position, priority, status, owner, watchers, tags, custom fields, open tasks and unread changes, with the Tracked items page's filters	Your Tracked items views, one at a time

For example, an assistant finds California's housing bills with search_records(kind="bill", filters={location: "CA", topic: "housing"}), runs a saved view with search_records(kind="bill", saved_view={names: ["Tax watchlist"]}), and finds when that view's bills are heard with search_records(kind="event", saved_view={kind: "bill", names: ["Tax watchlist"]}). Every result carries an id for get_record: a bill's looks like CA/2026/SB 52. For a governor or the President, get_record returns their terms and signing record rather than a legislator's profile.

Your tracked items#

With kind tracked_item, an assistant reads your organization's tracking exactly as the member who created the key sees it on Tracking › Tracked items: the items shared with them (all of them with Read All), and for a client member only their client's items and what's shown to clients. It can answer "which high-priority bills we oppose are still in committee?" with search_records(kind="tracked_item", filters={position: "oppose", furthest_stage: "in_committee"}) and follow each item's bill.id into the bill. It can run one of your Tracked items saved views with saved_view: {names: ["…"]}, and a bill search can ask for only the bills you track with tracked: true: each bill lists your organization's items for it, per client and your own, under tracking. Retired custom fields come back marked inactive. Reading never marks an item read, and it never includes notes or the files attached to them. The key's creator needs Read on Tracked items, and a client member needs MCP granted on their permissions. See Tracked items.

The server also offers three reference resources — capitolmath://meta/topics, capitolmath://meta/locations and capitolmath://meta/vocab — and two ready-made prompts, analyze_bill and legislator_profile.

Good to know#

It's your organization's API. The tools read the REST API with your key, so their requests count toward the organization's monthly quota and rate limit and follow your plan's rules — on the State plan, only your state. Most tool calls are one request; a few count one per record they read: comparing legislators counts one per legislator, and reading a governor's or the President's record counts two. See Authentication and permissions.
Saved views run as the key's creator. search_records runs only views the member who created the key can see. Name a view that doesn't exist, and the tool replies with the views it can see.
Congress is US. Use it wherever a tool takes a location.
A whip count is a prediction, not a record. Read its caveats before you repeat it. See Whip counts.

For each endpoint behind the tools, see the API reference.