# electionsmcp > An MCP-native election modeling tool. Model and map any 2028 U.S. race down to the precinct — > president, U.S. Senate, governor, U.S. House, and state legislature; primary or general. It maps > YOUR assumptions instantly on a live map; it is NOT an automated forecast. A human drives it in the > browser, or an AI agent drives the entire app over the Model Context Protocol (MCP). Every race rolls up from the same atoms: 163,925 U.S. precincts with 2024 results. Set candidates, persuade or mobilize demographic cohorts, drill into one race, roll up control of the chamber, and publish a shareable forecast — all by hand or by an agent over MCP. ## Connect over MCP - Endpoint (Streamable HTTP, JSON-RPC 2.0 over POST): https://www.electionsmcp.com/mcp - Legacy HTTP+SSE transport: https://www.electionsmcp.com/sse (advertises a POST /messages endpoint) - stdio clients (e.g. Claude Desktop): npx -y mcp-remote https://www.electionsmcp.com/mcp --header x-electionsmcp-key:YOUR_KEY - Auth (optional): header "Authorization: Bearer " or "x-electionsmcp-key: ". No key = a read/simulate sandbox; a key saves to the durable tier. Get a key by signing in at https://www.electionsmcp.com. - GET https://www.electionsmcp.com/mcp returns a machine-readable connection guide for any client. - First call once connected: the "help" tool — it returns all 203 tools and a typical workflow. ## What an agent can do (203 MCP tools) - Simulations: create_simulation, clone_simulation, share_simulation, publish_forecast, fork_forecast - Model: set_candidates, set_feature_percentages, apply_uniform_swing, apply_demographic_swing (persuasion / vote share), set_turnout (mobilization / vote weight), apply_swing_to_query - Navigate: set_cycle (2024/26/28/30), set_mode (general/primary), set_race_scope, resolve_geography - Roll up: get_tally, roll_up_race, roll_up_state_races, senate_control, roll_up_primary, get_impact_report - Precincts: list_precincts, query_precincts, set_precinct_pcts, clear_precinct_override - Annotate the map: add_annotation (pin / highlight targeted regions / note), list_annotations, remove_annotation - Feedback & support: submit_ticket (bug / feature request / question), list_tickets, get_ticket — reaches the team - Scenarios + versions (append-only): create_scenario, commit_version, diff_versions, restore_version, snapshot_simulation ## Audited tools (the trust system) electionsmcp audits its own MCP server: per-tool contract tests with semantic invariants (vote totals conserve, exactly 538 electoral votes, exactly 100 Senate seats, typed errors — never a silent wrong answer) run against this production endpoint. The site renders only what the audit proves; tools that fail are removed from the public pages automatically. - Live tool explorer (audited tools only): https://www.electionsmcp.com/tools - The full, unedited audit board (every tool, every status): https://www.electionsmcp.com/trust - Machine-readable feeds: https://www.electionsmcp.com/api/manifest and https://www.electionsmcp.com/api/audit-report - Contract-verified right now (128 of 203), grouped by what you use them for: Look up real results: - actual_contest — The real result of any single contest by its contest_id (from list_actual_contests) — works for every ballot line, including non-districted… - actual_coverage — Discover what REAL ingested election results are available to analyze — actual precinct-level returns (from RoutPoint), grouped by state × … - actual_results — The real result of one race, rolled up from its actual precinct returns: winner + party, margin (pp), Dem/Rep vote totals & pct, turnout, a… - actual_rollup — Aggregate real precinct returns up to county, district, or statewide totals for a state×office×year. - list_actual_contests — Browse the FULL ballot — every individual contest with real precinct returns, including down-ballot races that aren't districted (sheriffs,… - maine_live_map — LIVE TONIGHT — the Maine primary county map, packaged for client sites. - maine_live_results — LIVE TONIGHT (June 9, 2026) — Maine statewide primary, live election-night results: statewide reporting (counties/precincts reporting, ball… - query_actual_precincts — Analytical filter over real precinct returns: closest precincts, precincts a party won, turnout outliers — within one race or across a whol… - race_result — AUTHORITATIVE RESULT — the one trustworthy answer to "what is the result of this race?", from the certified precinct returns, with explicit… Mark up the map: - add_annotation — Pin a note or highlight on the map — an annotation that travels with the scenario, so collaborators see what the forecast is targeting at a… - clear_annotations — Remove all annotations from a scenario, or only those of one type when "type" is given. - list_annotations — List every annotation (pins, highlights, notes) on a scenario. - remove_annotation — Remove a single annotation by its id. Work as a team: - add_comment — TEAM (EM-123) — comment on any object in your active workspace, so discussion lives next to the artifact it is about (a scenario, dataset, … - add_to_campaign — TEAM (EM-122) — tag a resource into a campaign so it groups under that race. - assign_task — TEAM (EM-123) — assign a task to a teammate in your active workspace, optionally about a specific object (a scenario, dataset, dashboard, p… - create_campaign — TEAM (EM-122) — create a campaign: a container grouping ONE race's scenarios, datasets, polls, and dashboards inside your active workspace,… - create_workspace — TEAM (EM-122) — create a shared team workspace (a `w-…` id) that your whole team works inside, beyond per-resource grant_access. - get_account_overview — SESSION BOOTSTRAP — the whole account in ONE call, so an AI opening it cold (or at the start of a session) has full context without fanning… - get_activity_feed — TEAM (EM-123) — the shared activity feed for your active team workspace: who did what, newest-first. - get_campaign — TEAM (EM-122) — one campaign: its race scope + every resource tagged into it (scenarios, datasets, polls, dashboards). - get_campaign_plan — CAMPAIGN BRAIN — fetch a campaign plan by name (full object). - get_workspace — TEAM (EM-145) — the workspace object itself (name, owner, plan, member count, created_at, your role) — distinct from list_members, which is… - invite_member — TEAM (EM-122) — add a teammate to a team workspace by email with a role: admin (manage members + settings), manager (write + assign/coordin… - list_campaigns — TEAM (EM-122) — list the campaigns in your active workspace, each with its race scope + tagged-resource count. - list_comments — TEAM (EM-123) — the comment thread on one object in your active workspace, oldest-first, each with author, body, @mentions, parent_id (for … - list_members — TEAM (EM-122) — list a workspace's members and their roles (you must be a member). - list_notifications — TEAM (EM-123) — YOUR notification inbox across every workspace you belong to (newest first). - list_tasks — TEAM (EM-123) — tasks in your active workspace, newest-first. - list_workspaces — TEAM (EM-122) — list the team workspaces you can act in (every `w-` you are a member of), each with your role, plus your active + personal … - mark_read — TEAM (EM-123) — mark your notifications read. - remove_member — TEAM (EM-122) — remove a member from a workspace (they immediately lose access to its resources). - rename_workspace — TEAM (EM-145) — rename a team workspace (fixes a typo'd name; create_workspace previously made the name permanent). - set_campaign_plan — CAMPAIGN BRAIN — create or update the first-class plan for a race: win number, target %, the universes (mobilize/persuade/register), lever … - set_member_role — TEAM (EM-122) — change a member's role (admin|manager|analyst|viewer). - update_task — TEAM (EM-123) — update a task you were assigned (or any task if you are a manager/admin): change status (open|in_progress|done|cancelled), … Track the polls: - add_poll — Record a poll datapoint for a race in a simulation. - add_poll_wave — POLLING TIMELINE — store one poll wave in a named, org-scoped series so it can be trended and diffed wave-over-wave (generic ballot, favora… - average_polls — Compute a polling average per candidate for a race. - delete_survey — SURVEY-NATIVE STORAGE — delete a stored survey by id. - diff_poll_waves — POLLING TIMELINE — what moved between two waves of a series (defaults first→latest): per-metric change + the margin shift, with a headline … - get_poll_timeline — POLLING TIMELINE — the full wave series for a place, in date order, with wave-over-wave deltas per metric + a derived margin (D+/R+) and a … - get_survey — SURVEY-NATIVE STORAGE — the FULL stored instrument by survey_id: name/pollster/geo/field dates/n/moe/weighting + every question (real text,… - ingest_survey — SURVEY-NATIVE STORAGE — store a poll as the WHOLE instrument (not flattened to label-less metric-ids): every question with its real text, e… - list_polls — List all polls stored against a simulation, optionally filtered by race_key. - pollster_leaderboard — POLL ACCURACY (EM-111) — rank every stored, contest-linked poll in your library by accuracy: per-pollster mean absolute margin error (lower… - score_poll — POLL ACCURACY (EM-111) — grade a stored poll against the REAL contest result: poll margin vs actual margin, signed error (+ = overstated De… Model what-if scenarios: - apply_swing_to_query — Apply a uniform swing to every precinct matching a filter, in one call. - apply_uniform_swing — Apply a uniform swing in points toward one candidate across every feature in a level. - clone_simulation — Duplicate a simulation under a new name. - create_scenario — Create a new Scenario (a modeled path) — optionally inside a Race and seeded from a contest_id or an existing scenario (import_from). - create_simulation — Start a brand-new what-if model: an empty simulation of any race, ready for candidates, swings, and turnout. - get_simulation — Fetch the full state of a simulation: candidates per level, overrides per level, last modified. - list_candidates — List candidates currently configured for a simulation+level. - list_simulations — List all saved simulations in this workspace. - query_precincts — Query precincts with structured filters, sorted + trimmed server-side. - reset_overrides — Clear all manual overrides — the "reset to baseline" action. - set_candidates — Replace the entire candidate roster for a simulation+level in one call (add / edit / remove / reorder). - set_performance — Set a candidate's vote share or turnout in a specific county, district, state, or precinct — the unified override primitive. - set_turnout — Set the turnout (mobilization) model — president only. Plan a campaign: - campaign_brief — CAMPAIGN COCKPIT — one call, the whole state-of-play for any race, president → state house. - campaign_help — Campaign playbook — call this FIRST when the user is campaign staff (manager, finance, field, data, or the candidate). - candidate_overperformance — CANDIDATE QUALITY — how a real down-ballot candidate ran vs the TOP OF THE TICKET in the same district. - compute_vote_goal — How many votes a candidate needs to win a contest — the win number and remaining gap. - cost_model — Price a vote goal in dollars by channel — $ per net vote (a net vote = +1 to your margin) as a RANGE, not a false-precision point. - cost_to_win — The budget ask for a race: net votes needed to flip (half the current margin in votes) × public per-net-vote benchmarks across persuasion/t… - slate_digest — A monitoring board for a slate of races: one call returns each race's rating, margin, net-votes-to-flip and turnout, plus a compact snapsho… Save points & history: - commit_version — Save the scenario's current state as a new immutable, hash-stamped version in the append-only chain. - diff_versions — Structured diff between two versions of one scenario: which feature/precinct overrides changed (before/after) and how the top_line moved. - list_scenario_versions — The append-only version chain for a scenario, newest last, with per-version summary + top_line. - list_snapshots — List all snapshots taken against a simulation. - restore_snapshot — Roll a simulation back to a previously-captured snapshot. - restore_version — Set the scenario's working state back to a prior version's payload, and return that complete per-precinct `state` (so the map redraws to th… - snapshot_simulation — Capture the current state of a simulation as a labeled snapshot. Data warehouse & advanced: - create_collection — MANAGED STORE — define a typed collection (a "table") for arbitrary tenant data: voter file, donor file, canvass results, ad logs, anything. - delete_collection — MANAGED STORE — permanently drop a collection and ALL its records. - delete_dataset — CLIENT DATA HUB — permanently drop a dataset and ALL its rows, and clear any access grants on it. - describe_collection — MANAGED STORE — a collection's schema, key_field, record_count, and a sample of records. - describe_dimension — DEMOGRAPHIC SPINE — one dimension's canonical values, each with its synonyms (the pollster variants that resolve to it), hierarchy parent, … - get_dataset — CLIENT DATA HUB — inspect a dataset: its schema (grain, geo_key, declared metrics + aggregations), row_count, updated_at, your_role, and a … - grant_access — ACCESS CONTROL — share a dataset OR a collection you own with a teammate/partner account, by EMAIL (recommended; resolved to their account)… - identify_taxonomy — TAXONOMY GATE (EM-107) — the normalization primitive. - ingest_dataset — CLIENT DATA HUB — push the client's OWN per-geography metrics (voter-file / donor-file derived) into a named, workspace-scoped dataset that… - insert_records — MANAGED STORE — add records to a collection. - list_access — ACCESS CONTROL — the access list for a dataset or collection. - list_collections — MANAGED STORE — list this workspace's collections (name, fields, key_field, record count). - list_custom_taxonomies — TAXONOMY LAYER 3 (EM-107) — list this account's custom taxonomies, their nodes, and each node's links to canonical nodes. - list_datasets — CLIENT DATA HUB — list datasets you can see: `datasets` (ones you OWN, query by name) and `shared_with_me` (ones another account granted yo… - list_dimensions — DEMOGRAPHIC SPINE (EM-106) — list the canonical demographic dimensions available to this account: platform-seeded standards (gender, age, p… - list_unmapped_subgroups — DEMOGRAPHIC SPINE — the cleanup queue: raw subgroup labels present in your poll library that do NOT yet resolve to a canonical entity (so n… - migrate_collection_to_observations — TAXONOMY CUTOVER (EM-107) — push a collection's cells through the gate into the canonical observation store: each subgroup is normalized vi… - query_metric — CAMPAIGN HQ — the one read path for governed campaign metrics (the semantic layer behind Claude-composed dashboards). - query_observations — TAXONOMY (EM-107) — read the canonical observation store. - query_records — MANAGED STORE — read records from a collection. - resolve_dimension — TAXONOMY (EM-107) — return the full canonical node tree for one dimension: every node with its label, hierarchy (parent → children rollup),… - resolve_subgroup — DEMOGRAPHIC SPINE — resolve a raw pollster banner label to its ONE canonical entity. - review_taxonomy_matches — TAXONOMY GATE (EM-107) — the human-adjudication queue for low-confidence / unmatched values that identify_taxonomy could not auto-commit. - revoke_access — ACCESS CONTROL — remove a grantee's access to a dataset or collection you own/admin (by grantee_email or grantee_ws). - translate_taxonomy — TAXONOMY LAYER 3 (EM-107) — crosswalk two custom taxonomies via the canonical nodes both link to (spec §6). - upsert_dataset_rows — CLIENT DATA HUB — incrementally add/update rows by geo id WITHOUT replacing the whole dataset (daily ballot-return loads, new donors, a cor… Explore places & ballots: - election_calendar — THE PLANNER'S CALENDAR — what is on the ballot when. - get_demographic_report — DEMOGRAPHIC SPINE (EM-106) — RECALL. - get_geography — Boundary reference, children, and a demographic summary (county grain — ACS 2023; states and districts return boundary + identity only) for… - get_precinct — Get a single precinct by external_id (e.g. - list_contests — What is ACTUALLY on the ballot: the real contests in a geography for a cycle, from the ground-truth electoral calendar — president only in … - list_districts — List every district at a given race level. - list_precincts — List precincts in a state with 2024 D/R/total votes baked in. - precincts_in_district — Return precincts whose centroid falls inside the given district boundary. - query_demographic — DEMOGRAPHIC SPINE (EM-106) — the CROSS-POLL JOIN. - resolve_geography — Turn a place name or shorthand into its canonical geo_id — resolve natural-language or structured location input. Publish & share: - fork_forecast — Clone a published forecast as a new editable simulation in the caller's workspace. - list_dashboards — CAMPAIGN HQ — list the workspace's saved dashboards (id, name, scope, updated_at). - publish_forecast — Turn a simulation into a published forecast article. - revoke_share — Revoke a previously-minted public share token. - share_simulation — Mint a public read-only share token for a simulation. Find your way (discovery & trust): - get_catalog — DISCOVERY — find the right tool for any job: search and inspect the complete server-owned tool catalog, INCLUDING tools hidden from your cu… - help — High-level orientation for AI clients new to the simulator. - verify_audit — WITNESS AUDIT (EM-116) — re-verify the immutable, content-hashed audit chain of a scenario's committed versions (commit_version is the appe… Roll up the outcome: - get_impact_report — Nation-wide election impact across ALL 6 legislative levels in one call. - get_tally — Compute the current per-candidate tally for a simulation+level. - list_flipped — List features whose winner under the simulated overrides differs from the baseline — `count` is the FULL flip total; `flipped` returns up t… - roll_up_race — Roll up precincts to a race outcome under the current simulation. - roll_up_state_races — Roll up every race in scope at a single level for a state, in one call. - senate_control — Compute Senate control for a cycle using the real class calendar. Run the primaries: - list_primary_calendar — Return the ordered 2028 primary calendar for D or R: state by state, with date, type (primary/caucus), delegates, and tier (carve-out / sup… - roll_up_primary — The running delegate count. - set_primary_candidates — Define the candidate field for a party's presidential primary on this simulation (the GOP/Dem contenders). - set_primary_shares — Set one state's vote shares for a party's presidential primary (the percentage each candidate wins in that state). ## Strategic tool revelation (agent efficiency) - tools/list serves a PROFILE: keyless sessions see the 140-tool core modeling loop (~30% less schema context); an API key — or the header "x-electionsmcp-tools: full" — lists all 203. Gating is visibility-only: every tool stays callable regardless. - Discover anything hidden: get_catalog({query:"…"}) text-searches the FULL catalog (ranked, with gating reasons); get_catalog({tool:"name"}) returns that tool's complete inputSchema on demand. ## Race pages (human- and AI-readable) Each carries the race's facts, FAQ + HowTo structured data, and a deep link into the simulator. - 2028 races hub (the presidency + every U.S. Senate seat on the ballot): https://www.electionsmcp.com/2028 - 2028 presidential election map: https://www.electionsmcp.com/2028/president - 2028 Senate by state: https://www.electionsmcp.com/2028/senate/ — one page per seat up, e.g. https://www.electionsmcp.com/2028/senate/pennsylvania. Full list in https://www.electionsmcp.com/sitemap.xml ## Links - App: https://www.electionsmcp.com/ - Browse 2028 races: https://www.electionsmcp.com/2028 - Audited tool explorer: https://www.electionsmcp.com/tools · audit board: https://www.electionsmcp.com/trust - Live agent activity: https://www.electionsmcp.com/activity - MCP endpoint + connection guide: https://www.electionsmcp.com/mcp - Data: precinct-level U.S. electoral + geographic data (NYT Upshot, 2024)