# io.github.cyanheads/openstates-mcp-server (remote · openstates.caseyjhand.com)

Search bills, legislators, committees, and events across all 50 US states, DC, and 5 US territories.

- Trust score: 69/100 (medium)
- Change this week: +2
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- remote · `openstates.caseyjhand.com`: 69/100 (this document), [markdown](https://verifymcp.io/servers/cyanheads-openstates-mcp-server/openstates.md), [page](https://verifymcp.io/servers/cyanheads-openstates-mcp-server/openstates)
- npm · `@cyanheads/openstates-mcp-server`: 35/100, [markdown](https://verifymcp.io/servers/cyanheads-openstates-mcp-server/cyanheads-openstates-mcp-server.md), [page](https://verifymcp.io/servers/cyanheads-openstates-mcp-server/cyanheads-openstates-mcp-server)

## Channel facts

- Endpoint: `https://openstates.caseyjhand.com/mcp`
- Transports: `streamable-http`
- Auth: `none`
- Version: `0.3.0`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically against the live server, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Endpoint Security**: 66/100
  - The endpoint's TLS certificate is valid, in date, and uses a strong key.
  - Authorisation not fully verified: no authorisation is required to call this server, and 10 tool(s) never declared a destructiveHint. The MCP spec treats an absent hint as destructive by default, so we cannot call this surface safe.
  - HTTPS is enforced; there's no plaintext access path.
  - The HSTS (Strict-Transport-Security) header is present.
  - DNSSEC is configured correctly; the domain's records validate against the full chain to the root.
- **Transport & Reachability**: 100/100
  - Verified streamable-http transport via a live MCP handshake.
- **Schema Quality & AI Usability**: 75/100
  - 100% of prompts and resources have a non-trivial description (not blank, and not just the item's name).
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 3555 tokens (~253/item across 14 items; 10 tools + 4 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 17/100
  - Stability check failed: schema churn in the 8 days we've observed: 0 tool removals, 2 breaking changes, 0 auth/transport breaks, 0 additions.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
  - Structured output schemas are declared (100% of tools); any adoption earns full credit.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add --transport http cyanheads-openstates-mcp-server https://openstates.caseyjhand.com/mcp
```

### Codex

```toml
[mcp_servers.cyanheads-openstates-mcp-server]
url = "https://openstates.caseyjhand.com/mcp"
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cyanheads-openstates-mcp-server": {
      "type": "remote",
      "url": "https://openstates.caseyjhand.com/mcp",
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add cyanheads-openstates-mcp-server --url https://openstates.caseyjhand.com/mcp --transport streamable-http
```

### Hermes

```yaml
mcp_servers:
  cyanheads-openstates-mcp-server:
    url: "https://openstates.caseyjhand.com/mcp"
```

### Other

```json
{
  "mcpServers": {
    "cyanheads-openstates-mcp-server": {
      "type": "http",
      "url": "https://openstates.caseyjhand.com/mcp"
    }
  }
}
```

The mcpServers block is a cross-client convention. Remote transports vary, so check your client's docs.

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-03 (score 69, +1)

No change was recorded against any check on this day. Stability & Change Management went from 13 to 17.

### 2026-08-01 (score 68, +1)

No change was recorded against any check on this day. Stability & Change Management went from 7 to 10.

### 2026-07-31 (score 67, −2)

- [security regression] Stability: 0.13 → fail
- [functional regression] Schema quality: 222 → 253
- [functional] MCP protocol: Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.
- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server
- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-30 (score 69, +1)

No change was recorded against any check on this day. Stability & Change Management went from 10 to 13. That category is still filling its 30-day observation window: 3 days of observed history at the previous scan, 4 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-07-28 (score 68, +1)

No change was recorded against any check on this day. Stability & Change Management went from 3 to 7. That category is still filling its 30-day observation window: 1 days of observed history at the previous scan, 2 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-07-27 (score 67, +1)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-26 (score 66)

First indexed and scored.

## MCP tools (10)

### `openstates_search_bills` (~609 tokens)

Search Bills

Search state legislative bills across all covered US jurisdictions. Supports full-text search, jurisdiction/session filtering, subject tags, sponsor lookups, and sort order. Either jurisdiction or q (full-text) is required, and pairing them is the reliable form — a q-only search spans all 56 jurisdictions and exceeds the upstream timeout for a common term, though a distinctive one still returns quickly. include=sponsorships,actions returns sponsor and action history inline. sort=latest_action_desc surfaces bills currently moving. openstates_get_jurisdiction with include=legislative_sessions returns valid session identifiers for session filtering.

Input parameters:

- `action_since` (string): ISO 8601 date — only return bills with an action after this date (e.g., "2025-01-01").
- `chamber` (string): Filter by originating chamber. "upper" = Senate, "lower" = House/Assembly.
- `classification` (string): Bill classification: "bill", "resolution", "constitutional amendment", etc.
- `created_since` (string): ISO 8601 date — only return bills first entered in Open States after this date (e.g., "2025-01-01"). Use to find newly-introduced bills, as opposed to recently-updated or recently-acted-on.
- `include` (array): Related data to inline. "sponsorships" and "actions" cover most research needs without a separate openstates_get_bill call. "votes" adds full vote tallies and per-legislator positions.
- `jurisdiction` (string): State name, two-letter abbreviation, or OCD-ID (e.g., "Washington", "wa", or "ocd-jurisdiction/country:us/state:wa/government"). Required unless q is provided.
- `page` (integer): Page number (1-indexed).
- `per_page` (integer): Results per page. Maximum 20. Default 10.
- `q` (string): Full-text search across bill titles, abstracts, and text. Required unless jurisdiction is provided. Pair it with jurisdiction whenever a state is known — a q-only search over every jurisdiction times…
- `session` (string): Session identifier (e.g., "2025", "2025-2026", "2025rs"). Use openstates_get_jurisdiction with include=legislative_sessions to discover valid values. Omit to search across all sessions.
- `sort` (string): Sort order. Use "latest_action_desc" for bills currently moving through the legislature.
- `sponsor` (string): Filter by sponsor name or OCD person ID.
- `sponsor_classification` (string): Filter sponsor type: "primary", "cosponsor".
- `subject` (array): Filter to bills tagged with one or more subject categories.
- `updated_since` (string): ISO 8601 date — only return bills updated after this date (e.g., "2025-01-01").

Output parameters:

- `appliedFilters` (object): Filters applied to this query as the server received them, for agent self-verification of zero or unexpected results.
- `maxPage` (number): Total pages available.
- `notice` (string): Recovery hint when results are empty — names every filter that narrowed the query and suggests how to broaden. Absent when results are returned.
- `page` (number): Current page returned.
- `pagination` (object): Pagination metadata.
- `results` (array): Bills matching the search criteria.
- `totalCount` (number): Total bills matching the query across all pages.

### `openstates_get_bill` (~268 tokens)

Get Bill

Fetch full detail for a specific state bill. Accepts either the three-part path (jurisdiction + session + bill_id) or a direct OCD bill ID (openstates_id from search results). Use include to request votes, actions, sponsorships, documents, and versions in one call rather than searching again. include=votes returns the full vote tally and per-legislator positions. include=actions returns the complete action history. Prefer openstates_id when available to avoid session identifier lookup.

Input parameters:

- `bill_id` (string): Bill identifier as used by the legislature (e.g., "HB 1000", "SB 42"). Required with jurisdiction + session.
- `include` (array): Related data to inline. "sponsorships", "actions", "votes" are most commonly needed. "versions" and "documents" provide links to bill text and fiscal notes.
- `jurisdiction` (string): State name, abbreviation, or OCD-ID. Required when using path-based lookup with session + bill_id.
- `openstates_id` (string): OCD bill ID from openstates_search_bills results (e.g., "ocd-bill/..."). Preferred over the three-part path when available.
- `session` (string): Session identifier. Required with jurisdiction + bill_id.

Output parameters:

- `abstracts` (array): Bill abstracts when include=abstracts is requested.
- `actions` (array): Full action history when include=actions is requested.
- `classification` (array): Bill classifications.
- `documents` (array): Bill documents (fiscal notes, etc.) when include=documents is requested.
- `first_action_date`: Date of first recorded action.
- `from_organization` (object): Originating chamber.
- `id` (string): OCD bill ID.
- `identifier` (string): Bill identifier as used by the legislature.
- `jurisdiction` (object): Originating jurisdiction.
- `latest_action_date`: Date of most recent action.
- `latest_action_description`: Most recent action description.
- `latest_passage_date`: Date bill passed (when applicable).
- `openstates_url` (string): Open States URL for this bill.
- `other_identifiers` (array): Alternate identifiers when include=other_identifiers is requested.
- `other_titles` (array): Alternate titles when include=other_titles is requested.
- `related_bills` (array): Related bills when include=related_bills is requested.
- `session` (string): Legislative session identifier.
- `sources` (array): Source documents when include=sources is requested.
- `sponsorships` (array): Sponsorships when include=sponsorships is requested.
- `subject` (array): Subject tags.
- `title` (string): Bill title.
- `updated_at` (string): Timestamp Open States last updated this record — the field openstates_search_bills sorts by under the default sort=updated_desc.
- `versions` (array): Bill text versions when include=versions is requested.
- `votes` (array): Vote events when include=votes is requested.

### `openstates_search_people` (~702 tokens)

Search People

Search state legislators and officials by name, jurisdiction, chamber, or district, or fetch specific people by OCD person ID. Party is reported on every result but cannot be filtered on — narrow by party after the call. Either jurisdiction or id is required — a search spanning all 56 jurisdictions exceeds the upstream timeout, including a name-only one, so scope every call to a single state or to specific person IDs. Use openstates_list_jurisdictions to pick a jurisdiction, or openstates_get_legislators_by_location when you have coordinates but no state. id takes the person IDs that openstates_get_bill sponsorships and openstates_get_committee memberships hand back, and resolves any number of them in one call. Supports name substring matching (case-insensitive). org_classification targets a role type: "upper" for Senate, "lower" for House/Assembly, "executive" for governors and executive officials, and "legislature" for every legislator — both chambers merged into one paginated set (all upper members, then all lower), which excludes executive-branch officials. Omitting org_classification is not the same as "legislature": it returns every officeholder, executive officials included. include=offices adds phone, fax, and address. include=links adds website and social links.

Input parameters:

- `district` (string): District label (e.g., "1", "37", "At-Large"). Formats vary by state.
- `id` (array): OCD person IDs (e.g., "ocd-person/9eddb3cd-868e-42ba-831a-b415fd7ed445"). Required unless jurisdiction is provided — it returns exactly these people, so it scopes the call on its own and needs no jur…
- `include` (array): Related data to inline. "offices" includes phone, fax, and address. "links" includes website and social links. "other_names" includes alternate/former names, "other_identifiers" cross-system IDs, and…
- `jurisdiction` (string): State name, abbreviation, or OCD-ID. Required unless id is provided — an all-states search exceeds the upstream timeout, so every call must be scoped to a single jurisdiction or to specific person ID…
- `name` (string): Name or partial name to match (case-insensitive substring). Narrows within the jurisdiction; it does not substitute for one.
- `org_classification` (string): Filter by role type. "upper" = Senate, "lower" = House/Assembly, "executive" = governors and executive officials, "legislature" = every legislator (both chambers merged into one paginated set, all up…
- `page` (integer): Page number (1-indexed).
- `per_page` (integer): Results per page. Maximum 20.

Output parameters:

- `appliedFilters` (object): Filters applied to this query as the server received them, for agent self-verification of zero or unexpected results.
- `maxPage` (number): Total pages available.
- `notice` (string): Recovery hint when results are empty. Absent when results are returned.
- `page` (number): Current page returned.
- `pagination` (object): Pagination metadata.
- `results` (array): Legislators matching the search criteria.
- `totalCount` (number): Total legislators matching the query across all pages.

### `openstates_get_legislators_by_location` (~271 tokens)

Get Legislators by Location

Find every legislator representing a geographic coordinate — both tiers. Pass latitude and longitude to get the state senators and representatives for that location (and potentially governor/executive officials), plus the coordinate's two US Senators and its US Representative. jurisdiction.classification separates the tiers: "state" is a state legislature, "country" is the US Congress. current_role.org_classification does not — it is "upper"/"lower" for a US Senator exactly as for a state senator. Useful for constituent-to-representative matching, address-based policy research, and electoral boundary analysis. This server does not geocode addresses — the caller must provide decimal-degree coordinates. Use include=offices to get contact information alongside the legislator list.

Input parameters:

- `include` (array): Related data to inline. "offices" includes phone, fax, and address. "links" includes website and social links. "other_names" includes alternate/former names, "other_identifiers" cross-system IDs, and…
- `latitude` (number, required): Latitude in decimal degrees (e.g., 47.6062 for Seattle, WA).
- `longitude` (number, required): Longitude in decimal degrees (e.g., -122.3321 for Seattle, WA).

Output parameters:

- `count` (number): Number of legislators returned for this coordinate.
- `federalCount` (number): Results serving the US Congress (jurisdiction.classification = "country") — the coordinate's two US Senators and its US Representative.
- `legislators` (array): Legislators representing the given coordinate.
- `notice` (string): Present when no legislators were found — explains why (e.g., location outside US boundaries or unsupported territory).
- `stateCount` (number): Results serving a state legislature (jurisdiction.classification = "state").

### `openstates_search_committees` (~311 tokens)

Search Committees

List committees for a jurisdiction. jurisdiction is required — a request spanning all 56 jurisdictions exceeds the upstream timeout, so scope every call to a single state; use openstates_list_jurisdictions to pick one. Experimental — Open States is actively working to restore committee support and not all states have data. Use chamber to scope to upper (senate) or lower (house) committees. Use classification=subcommittee to find subcommittees of a parent. Use include=memberships to get the full roster with member roles. The coverageNote field in the output will always note the experimental coverage limitations.

Input parameters:

- `chamber` (string): Filter by chamber. "upper" = Senate, "lower" = House/Assembly.
- `classification` (string): Filter to parent committees or subcommittees only. Omit for all.
- `include` (array): Related data to inline. "memberships" includes the full roster with member roles. "links" includes the committee homepage and reference links, and "sources" the provenance URLs behind the record.
- `jurisdiction` (string, required): State name, abbreviation, or OCD-ID. Required — an all-states request exceeds the upstream timeout, so every call must be scoped to a single jurisdiction.
- `page` (integer): Page number (1-indexed).
- `parent` (string): OCD organization ID of a parent committee to retrieve its subcommittees.
- `per_page` (integer): Results per page. Maximum 20.

Output parameters:

- `appliedFilters` (object): Filters applied to this query as the server received them, for agent self-verification of zero or unexpected results.
- `coverageNote` (string): Committee data is experimental — not all states have coverage in Open States. Empty results may indicate the state lacks data, not that no committees exist.
- `maxPage` (number): Total pages available.
- `page` (number): Current page returned.
- `pagination` (object): Pagination metadata.
- `results` (array): Committees matching the search criteria.
- `totalCount` (number): Total committees matching the query across all pages.

### `openstates_get_committee` (~124 tokens)

Get Committee

Fetch committee detail by OCD organization ID. Returns name, classification, and membership roster when include=memberships is requested. Experimental — not all states have committee data in Open States. Obtain the committee_id from openstates_search_committees.

Input parameters:

- `committee_id` (string, required): OCD organization ID (from openstates_search_committees results).
- `include` (array): Related data to inline. "memberships" includes the full roster with member roles. "links" includes the committee homepage and reference links, and "sources" the provenance URLs behind the record.

Output parameters:

- `classification` (string): Committee classification: "committee" or "subcommittee".
- `id` (string): OCD organization ID.
- `links` (array): Committee homepage and reference links when include=links is requested.
- `memberships` (array): Membership roster when include=memberships is requested.
- `name` (string): Committee name.
- `parent_id`: OCD ID of parent committee, or null for top-level committees.
- `sources` (array): Provenance sources when include=sources is requested.

### `openstates_search_events` (~340 tokens)

Search Events

Search hearings, floor sessions, and committee meetings. jurisdiction is required — the Open States events endpoint has no all-states search, so scope every call to a single state; use openstates_list_jurisdictions to pick one. Experimental — most states do not publish event data to Open States. Use after and before to scope to a date range. Set require_bills=true to filter to events with bills on the agenda, which is the most useful filter for tracking legislation through committee. Use include=agenda,participants for full meeting context. Empty results often indicate the state lacks event data rather than no events occurring.

Input parameters:

- `after` (string): ISO 8601 datetime — events starting after this time. Use to find upcoming hearings.
- `before` (string): ISO 8601 datetime — events starting before this time.
- `include` (array): Related data to inline. "agenda" includes the meeting agenda with bill references. "participants" includes the committee or chamber hosting the event. "links" and "media" add related URLs and recordi…
- `jurisdiction` (string, required): State name, abbreviation, or OCD-ID. Required — the Open States events endpoint has no all-states search, so every call must be scoped to a single jurisdiction.
- `page` (integer): Page number (1-indexed).
- `per_page` (integer): Results per page. Maximum 20.
- `require_bills` (boolean): When true, only return events with at least one bill on the agenda. Most useful for tracking legislation through committee.

Output parameters:

- `appliedFilters` (object): Filters applied to this query as the server received them, for agent self-verification of zero or unexpected results.
- `coverageNote` (string): Event data is experimental — most states do not publish event data to Open States. Empty results may indicate the state lacks data, not that no events occurred.
- `maxPage` (number): Total pages available.
- `notice` (string): Recovery hint when results are empty. Absent when results are returned.
- `page` (number): Current page returned.
- `pagination` (object): Pagination metadata.
- `results` (array): Events matching the search criteria.
- `totalCount` (number): Total events matching the query across all pages.

### `openstates_get_event` (~125 tokens)

Get Event

Fetch full event detail by OCD event ID. Returns agenda, participants, media links, and associated documents when requested via include. Experimental — event coverage is limited in Open States. Obtain the event_id from openstates_search_events.

Input parameters:

- `event_id` (string, required): OCD event ID (from openstates_search_events results).
- `include` (array): Related data to inline. "agenda" and "participants" are most useful; "links", "media", and "documents" add related URLs, recordings, and files, and "sources" the provenance URLs behind the record.

Output parameters:

- `agenda` (array): Agenda items when include=agenda is requested.
- `classification` (string): Event classification.
- `description` (string): Event description.
- `documents` (array): Document links when include=documents is requested.
- `end_date` (string): Event end datetime. Absent when not recorded.
- `id` (string): OCD event ID.
- `jurisdiction` (object): Hosting jurisdiction.
- `links` (array): Event links when include=links is requested.
- `location` (object): Event location when available.
- `media` (array): Media links when include=media is requested.
- `name` (string): Event name.
- `participants` (array): Participants when include=participants is requested.
- `sources` (array): Provenance sources when include=sources is requested.
- `start_date` (string): Event start datetime.
- `status` (string): Event status.

### `openstates_list_jurisdictions` (~327 tokens)

List Jurisdictions

List all jurisdictions covered by Open States — all 50 states, DC, and 5 US territories (American Samoa, Guam, Northern Mariana Islands, Puerto Rico, and the US Virgin Islands): 56 in total, returned complete in a single default call. Returns coverage metadata: latest bill update time, latest people update time, and optionally all legislative sessions with their identifiers. Use this when you need to discover valid session identifiers for a state before calling openstates_search_bills with a session filter. The legislative_sessions include option returns all historical and current sessions — always check valid session identifiers here before using them in bill searches, since formats vary widely by state (e.g., "2025", "2025-2026", "2025rs", "2025s1").

Input parameters:

- `classification` (string): Filter by jurisdiction type. Use "state" (default) for all 50 states, DC, and the 5 US territories.
- `include` (array): Related data to inline. "legislative_sessions" returns all session identifiers and date ranges — required when you need to discover valid session values for bill searches. "organizations" lists the j…
- `page` (integer): Page number (1-indexed).
- `per_page` (integer): Results per page (upstream maximum 52). The default call returns the complete state inventory (56) in one response by fetching and merging the pages server-side; set a smaller value only to page manu…

Output parameters:

- `maxPage` (number): Total pages available.
- `page` (number): Current page returned.
- `pagination` (object): Pagination metadata.
- `results` (array): Jurisdictions matching the filter.
- `totalCount` (number): Total jurisdictions matching the filter across all pages.

### `openstates_get_jurisdiction` (~220 tokens)

Get Jurisdiction

Fetch full metadata for a specific jurisdiction including all legislative sessions, their identifiers, and coverage dates. Use when you need to know the exact session identifier for a state before filtering bill searches — session formats vary widely (e.g., "2025", "2025rs", "2025s1"). Jurisdiction IDs follow OCD format: ocd-jurisdiction/country:us/state:{abbr}/government (e.g., ocd-jurisdiction/country:us/state:wa/government). State names (e.g., "Washington") and two-letter abbreviations (e.g., "wa") are also accepted.

Input parameters:

- `include` (array): Related data to inline. "legislative_sessions" returns all historical and current sessions with identifiers and date ranges. "organizations" lists the jurisdiction's legislative chambers and executiv…
- `jurisdiction_id` (string, required): OCD jurisdiction ID, state name (e.g., "Washington"), or two-letter abbreviation (e.g., "wa").

Output parameters:

- `classification` (string): Jurisdiction type.
- `id` (string): OCD jurisdiction ID.
- `latest_bill_update` (string): ISO 8601 timestamp of most recent bill data update.
- `latest_people_update` (string): ISO 8601 timestamp of most recent people data update.
- `latest_runs` (array): Recent scraper runs when include=latest_runs is requested.
- `legislative_sessions` (array): All legislative sessions when include=legislative_sessions is requested.
- `name` (string): Jurisdiction name.
- `organizations` (array): Legislative chambers and executive bodies when include=organizations is requested.
- `url` (string): Official legislature URL.

## Diagnostics

Captured diagnostic sections: TLS, DNSSEC, Authorisation, Transports. The full working is on the page: https://verifymcp.io/servers/cyanheads-openstates-mcp-server/openstates#diagnostics

## Score history

- 2026-08-03: 69
- 2026-08-02: 68
- 2026-08-01: 68
- 2026-07-31: 67
- 2026-07-30: 69
- 2026-07-29: 68
- 2026-07-28: 68
- 2026-07-27: 67
- 2026-07-26: 66

## Links

- Remote endpoint: https://openstates.caseyjhand.com/mcp
- Repository: https://github.com/cyanheads/openstates-mcp-server
- Changelog RSS feed: https://verifymcp.io/servers/cyanheads-openstates-mcp-server/openstates/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/cyanheads-openstates-mcp-server/openstates/changelog.json
- HTML version of this page: https://verifymcp.io/servers/cyanheads-openstates-mcp-server/openstates