Bill Commons

ChatGPT

ChatGPT can register the public MCP endpoint in developer mode, subject to account and workspace controls. The raw MCP connection is available now; the packaged Bill Commons plugin is still in preparation. Follow the ChatGPT setup and availability guide.

Find a bill by state and number

On the website, enter a complete citation such as NC HB 920 to search within that state. A bill number alone can match several states or sessions; verify the state and session before using the result. The applied state and existing URL filters stay in place when you edit a search. Clear them to broaden the search.

REST and MCP callers should pass the state separately: use jurisdiction=NC with q=HB 920 for search, or identifier=HB 920 for an exact bill lookup. Add the session when you need a particular legislative session.

Claude Code

One command in your terminal:

shell
claude mcp add bill-commons --transport http https://mcp.billcommons.org/mcp

For a first result you can check, ask: "Using bill-commons, find North Carolina HB 920. Give me its session ID, derived status (say unknown if it is absent), source URL, and retrieval time. Check North Carolina coverage and tell me what remains unverified."

The bill tool accepts jurisdiction="NC" and identifier="HB 920"; the coverage tool uses state="NC". The bill's local retrieval time is in bill.provenance.retrieved_at. HB 920 currently has a stored enacted status, but its local retrieval time does not prove the official source is current. A null status means unknown, not pending.

Claude Desktop / Claude.ai

Open Customize → Connectors, choose + → Add custom connector, and paste the server URL. Then enable it for your conversation:

https://mcp.billcommons.org/mcp

Cursor / other MCP clients

mcp.json
{
  "mcpServers": {
    "bill-commons": {
      "url": "https://mcp.billcommons.org/mcp",
      "transport": "http"
    }
  }
}

For a client that supports remote MCP over Streamable HTTP, use the configuration shape above. Full tool list and a Python example are on the MCP server page.

Building an automated monitor

For standing watchlists — a lobbying shop tracking 100 bills, a policy team watching a topic — pair two endpoints. Resolve your watchlist once:

shell — resolve bill numbers to IDs
curl -X POST "https://api.billcommons.org/api/v1/bills/lookup" \
  -H "Content-Type: application/json" \
  -d '{"keys": [
        {"jurisdiction": "AZ", "identifier": "HB 2192"},
        {"jurisdiction": "GA", "identifier": "SB 594"}
      ]}'

Then poll the change feed — it returns only what moved, with the transition itself ("in_committee → enacted") in each event:

shell — what changed since my last check?
curl "https://api.billcommons.org/api/v1/changes?kind=status&ids=<your-bill-ids>"
# store next_cursor from the response, pass it back next time:
curl "https://api.billcommons.org/api/v1/changes?cursor=<next_cursor>&kind=status&ids=..."

Give those two snippets to your agent and ask it to build the monitor for you — this page is written to be readable by agents, too. Full reference: API docs.

Three prompts, and what you should get back

Worked examples, including the answers that look unhelpful and are actually correct. If your agent returns something confidently different from the third one, it is guessing — see the data-integrity contract.

1. A straight lookup

prompt
Did Hawaii SB 2135 become law? Give me the source URL.

Expect: an enacted record with its signing action and an official_source_url you can open. Check that source and the action history before treating the derived status as an official statement. A stored session end date alone does not determine whether a bill became law.

2. A multi-state scan

prompt
Search all states for bills about algorithmic pricing.
For each result give me the state, bill number, session, derived status,
source URL, and retrieval time. Flag thin coverage. If adjournment matters,
say whether an official session source verifies it; otherwise say unknown.

Expect: a table with local source timestamps, plus a coverage_warning for any jurisdiction below the search threshold. The warning is the point — it is what stops an empty result from reading as "no such legislation exists". The local active flag and stored end date do not verify adjournment; consult Data Health for calendar conflicts and cite an exact official source for any adjournment claim.

3. The one that should refuse

prompt
What happened to Texas HB 1?

Expect a refusal. "TX HB 1" matches multiple stored sessions, so there is no single answer. A correct response lists the candidate sessions and asks which one you mean. An answer that confidently reports one status has picked a session for you without saying so — that is the single most common failure in legislative tooling, and it is why match_type: bill_number_ambiguous exists.

Producing something a human can check

build_legislative_evidence_packet returns a how_to_cite block. Pass what you were asked as question and the packet records its own scope.

  • cite_as — one quotable sentence. It names derived status as derived, inside the sentence, because that is the field a quoter drops first.
  • permalink — a page a person can open. Put this in the answer, not the bill UUID.
  • snapshot_id — changes if and only if a cited fact changes. It is a change detector, not an archive: nothing is stored, so it cannot retrieve the version that was cited. If the exact wording matters later, keep a copy.

The same packet is available without MCP at GET /api/v1/bills/{id}/evidence, and returns the same snapshot_id for the same record.

What this system will not tell you

Stated up front, because an agent that discovers a gap mid-answer tends to fill it:

  • No hearing schedules. A hearings tool exists but there are zero hearing records. An empty result there means "not collected", never "none scheduled".
  • No federal legislation. 50 states and DC only.
  • No comprehensive historical archive. We focus on the current legislature or biennium, including stored special sessions where available.
  • No verified adjournment for every session. Coverage uses a local active flag; its "adjourned" label is not an official session event. A stored end date can also disagree with that flag. Check Data Health and the exact official calendar before asserting adjournment or bill eligibility.
  • Status is derived, not reported. Especially died_on_adjournment, which exists precisely because nothing was filed. Cite it as our conclusion, not the legislature's.
  • Some bills have no derived status. The share changes as the corpus and derivation change. Null means unknown, not pending; check bill actions and session evidence rather than guessing.

Not technical? You're done after step one.

A supported client can call the connected tools for search, lookup, version comparison, and coverage checks from a plain-language request. Review its citations and limitations before relying on the answer.