# electionsmcp > Build user-controlled election scenarios at the finest supported local grain, compare candidates, and coordinate campaign work through MCP. The canonical mixed-grain 2024 presidential baseline uses verified precinct or reporting-unit results where supported, with declared county/state fallbacks elsewhere. Results are approximate. Precinct and county totals may vary because of source coverage, reporting, and geographic differences. Set candidates, adjust explicit vote-share and turnout assumptions, explore supported geography, compare versioned scenarios, and carry the current selection into War Room conversations and tasks. ## 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 the retained workflow for the caller's authorized profile. - Prompts (prompts/list, prompts/get; slash commands in Claude Code and Codex): check-in, open-race, model-swing, connect-check, daily-brief, and use- for every tool in your profile. ## Quickstarts (goal → tool recipe) - Build a presidential scenario: create_simulation → set_cycle(2028) + set_mode("general") → set_candidates(level:"president") → set_performance / set_turnout — your assumptions → get_tally("president") — the Electoral College result → list_scenario_versions / diff_versions — compare versions → share_simulation — a public read-only scenario link - Model a presidential primary: create_simulation → set_mode("dem_primary_2028" or "rep_primary_2028") → set_primary_candidates — define the prospective field → set_primary_shares — model states → roll_up_primary — calculate delegates → set_compare_paths — compare candidate paths - Explore a scenario by geography: bind_session({page_url}) when a model is already open → get_view — read the exact scenario and selection → get_shapes(layer:"actuals:pres_2024") — load supported geography → aggregate_precincts(simulation_id) — scenario-scoped local rollup with provenance → render_view — create a map from the same scenario version - Coordinate campaign work: create_campaign — establish the campaign context → list_people — find collaborators → add_map_comment — discuss the selected geography → assign_task — turn the selection or conversation into work → membership_summary — read concise leadership status - Share a modeled result: read the exact scenario version with get_scenario → share_simulation — mint a public read-only scenario link → authenticate when you need generate_report — create a durable report pinned to that version ## What an agent can do - Model: create_simulation, create_scenario, set_candidates, set_performance, set_turnout, get_tally - Presidential primaries: set_primary_candidates, set_primary_shares, roll_up_primary, set_compare_paths - Geography: resolve_geography, get_view, get_shapes, aggregate_precincts, render_view - Compare and preserve scenarios: list_scenario_versions, diff_versions, restore_version - Candidate views: search_candidates, list_modeled_candidates, candidate_standing - Contextual War Room: add_map_comment, list_map_comments, react_map_comment, resolve_map_comment - Authenticated campaign operations: create_campaign, campaign_status (the daily brief in one read), list_people, assign_task, list_tasks, membership_summary - Outputs and trust: data_provenance, verify_audit, generate_report, share_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 endpoint. Normal discovery is limited to the retained Core and authenticated Workbench product profiles. - Contract-verified retained Core tools right now: 147 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 scenario is targeting at a glance. - 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. Model what-if scenarios: - add_candidate — Add a candidate to the candidates list for a simulation+level. - aggregate_precincts — Roll up the active user-controlled scenario from its canonical precinct and fallback atoms, returning modeled totals plus the scenario's 2024 baseline comparison and provenance. - apply_calendar_scenario — Apply a saved calendar scenario BY REFERENCE to a simulation — sets the sim's Democratic calendar to that ordering (reusing the define_dem_calendar path, so the delegate math… - apply_primary_cohort — BULK conditional primary edit — for every precinct in a HOUSE district that matches a 2024 cohort filter, set the candidate shares, in ONE call (instead of one… - apply_swing_to_query — Apply a uniform swing or an explicit per-precinct weights vector to a filtered cohort in one atomic call. - apply_uniform_swing — Apply an incremental swing in points toward one candidate at the requested office. - clear_feature_override — Clear the manual percentage override on a single feature (county/state/district), reverting it to its baseline. - clear_precinct_override — Remove a precinct-level override from a simulation, reverting that precinct to its 2024 baseline. - clear_race_scope — Remove the race scope from a simulation, returning it to national/retrospective mode. - 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. - delete_simulation — Permanently delete a simulation. - get_scenario — A Scenario at its latest version (or a specified version_id): metadata (incl. - get_simulation — Read the canonical simulation/scenario state, including candidates, race scope, geography overrides, active version identity, provenance, and optional summary or selected… - list_candidates — List candidates currently configured for a simulation+level. - list_precinct_overrides — List every precinct override stored in a simulation. - list_simulations — List saved simulations in this workspace (id, name, level, cycle, mode, contest_id, last-modified; rows stamped with an identity also carry created_by/updated_by member user_ids). - remove_candidate — Remove one candidate from a simulation+level roster (and drop them from any feature overrides). - 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_cycle — Set the election cycle modeled by the active scenario. - set_feature_percentages — Override the vote percentages on a single feature. - set_mode — Set presidential modeling mode to general, 2028 Democratic primary, or 2028 Republican primary. - set_performance — Set a candidate's vote share, such as the Democratic candidate to 54%, in one specific county, district, state, or precinct (the general-election override). - set_precinct_pcts — Set a precinct-level override in a simulation. - set_race_scope — Bind the canonical scenario to one race/campaign so its map, tally, candidates, War Room context, operations, outputs, and MCP actions share the same race identity. - set_swings — Persist the swing-slider state so a scenario built by hand in the browser (uniform + demographic share swings, the swing target, and the demographic region scope) survives reload. - set_turnout — Set the turnout (mobilization) model. - update_scenario — Edit a Scenario's name / description / tags. Data warehouse & advanced: - add_map_comment — Leave a Google-Docs-style COMMENT on the scenario map — a threaded, resolvable discussion anchored to a place. - analyze_primary_inflections — INFLECTION + SENSITIVITY analysis of a modeled presidential primary — under YOUR scenario's assumptions: not just who leads, but when your modeled race clinches and which… - announce_presence — HEARTBEAT — announce that this session (a browser tab or an MCP agent) is live in the workspace, optionally on one scenario. - answer_assumption — SCENARIO TRUST assumptions ledger (tk_960747792b23d3) — record a question you asked the user (or a premise you were given) and the answer that now drives this scenario's… - billing_status — BILLING — your subscription state: {billing_enabled, logged_in, plan (personal|team|null), status, active, renews, can_save}. - bind_session — BIND this agent session to the USER'S OPEN /sim — the session-bootstrap contract (tk_2ba54e8466bc19 / tk_7069d33b0c682e). - bulk_set_primary_shares — Write user-authored presidential-primary shares across many retained state or county geographies in one call. - candidate_path_explainer — PATH-TO-THE-NOMINATION explainer — for each candidate in a presidential-primary scenario (or one candidate_id), a DERIVED, plain-numbers account of HOW they win or WHY they… - candidate_standing — PORTAL — one candidate/official's standing across every race you model them in. - check_workspace_consistency — SCENARIO TRUST cross-scenario consistency sweep (tk_57e0d6adfac63d) — do this workspace's primary scenarios contradict each other? - confirm_connection — CUSTOMER SETUP — confirm a connection challenge THROUGH the MCP pipe: proves this key reaches this account (and workspace, when bound), records the client family, and advances… - connection_status — WHO AM I — how THIS session is authenticated and which workspace this request resolved to. - create_connection_challenge — CUSTOMER SETUP — mint a short-lived (15 min), ONE-TIME connection challenge for a setup session you own. - create_custom_candidate — Create a workspace-scoped prospective or write-in candidate with a stable identity, party, color, and optional office, then add that identity to canonical general- or… - create_race — Instantiate a tenant workspace (a Race) on a real-world Contest. - delete_race — Delete one workspace-scoped race. - delete_report — Delete one generated, workspace-scoped scenario report. - describe_open_campaign — Show the agent the campaign the user has OPEN right now, as one editable packet. - diff_calendar_scenarios — Diff two calendar orderings — each an id/name of a saved calendar scenario, or the literal "default" (the platform calendar). - exit_primary_candidate — Remove a candidate from a party's presidential-primary FIELD and REDISTRIBUTE their modeled vote share to the survivors in one atomic, provenance-carrying edit — the "so-and-so… - exposure — Run a deterministic swing-sensitivity sweep over the active user-controlled scenario and return the modeled control curve, swing-to-flip values, and most sensitive races. - focus_view — Fly the LIVE map camera to a geography — frame the state / county / district / precinct the viewer is watching, so "show them the decisive counties" actually moves the view… - get_ballot_order — BALLOT DESIGN — read back the ballot order recorded by set_ballot_order for a simulation+level: every roster candidate with its printed ballot position (candidates with a… - get_election_dates — When is the New Hampshire primary? - get_geo_knowledge — STRATEGIC KNOWLEDGE — the documented ruleset + knowledge for a geography, so an AI does not have to KNOW the rules; the platform supplies them. - get_manual_edits — Every manual edit in a scenario — the human's (or an agent's) overrides — in one scenario-scoped read, so a connected AI can see exactly what has been modeled and the deltas it… - get_plan_catalog — COMMERCIAL CATALOG — the server-owned plan catalog every surface consumes (/pricing, /get-started, account billing, provisioning): six active client types with label, audience,… - get_provisioning_status — CUSTOMER SETUP — the per-step provisioning state for a setup session you own: queued/running/done/failed with the exact failed step and a safe retry (provision_customer… - get_race — One Race with its contest, scenario list, and latest top-line per scenario. - get_view — Read the exact map/view state the application renders for a canonical scenario: headline totals, selected geography, modeled feature colors, annotations, primary-calendar… - list_calendar_scenarios — List the named calendar orderings saved in your workspace (save_calendar_scenario), newest first, optionally filtered by party. - list_custom_candidates — List the workspace's custom (write-in) candidates created via create_custom_candidate — the non-canonical field, distinct from the baked candidate registry. - list_geo_knowledge — List your workspace's CUSTOM geo-knowledge overlays (the rows set_geo_knowledge has written), newest grain first. - list_map_comments — List one campaign's map comments on a scenario (oldest-first), each with its campaign_id, anchor, author, body, @mentions, parent_id, and resolved state. - list_map_themes — MAP THEMES — the audience-preset registry (tk_bb87df86fdbc28): every theme with its semantic color tokens (party safe/likely/lean steps, tossup, missing, independent,… - list_modeled_candidates — PORTFOLIO — every candidate or elected official you are modeling, unioned across ALL of your simulations and every level, deduped by name+party. - list_presence — WHO IS LIVE in this workspace right now — every browser tab and MCP agent with a presence heartbeat in the last ~45s, one row per actor: {actor, name, color, scenario_id (the… - list_races — List the Races (contest workspaces) in this workspace, with scenario counts. - list_scenarios — Page saved scenarios/simulations in this workspace by updated_at descending and scenario_id ascending, without version blobs. - list_siblings — List scenario branches that share a common parent so user-authored alternatives remain navigable and comparable. - list_threads — The War Room as ONE campaign-scoped feed of THREADS — full discussion context in a single call. - list_workspace_comments — List contextual War Room discussion across the active workspace, optionally limited to one campaign. - lookup_address — Resolve a US street address, ZIP, state, or U.S. - manage_billing — BILLING — returns {portal_url} to the Stripe Customer Portal, where the USER can update payment, switch plan, or cancel (opened in a browser). - optimize_calendar — RANK primary-calendar orderings for a candidate against the sim's modeled per-state delegate hauls — which calendar order best helps candidate X. - primary_batch_edit — ATOMIC batch-edit transaction for a PRIMARY scenario — validate, preview, apply, and roll back a whole SET of candidate / share / calendar edits as ONE transaction. - primary_narrative — DATA-ONLY narrative package for a presidential-primary scenario — the STORY of the race as structured data an AI client turns into its own storyboard, press piece, memo, or… - primary_state_effective — ONE STATE's primary exactly as the delegate count sees it — the per-state READ view of roll_up_primary. - provision_customer — CUSTOMER SETUP — run (or RESUME) the checkpointed provisioning saga for a setup session you own: exactly one workspace with its client type, owner membership, roster record and… - react_map_comment — Toggle an emoji reaction on a War Room chat message (map comment): adds the caller to reactions[emoji] if absent, removes them if present. - remove_map_comment — Delete a map comment by id (soft-delete, so threads stay intact). - rename_simulation — Rename a simulation/scenario — give the map a real title instead of the stuck default. - render_chart — share_comparison compares candidate shares for two saved versions of one model or two same-contest statewide general-election models. - render_view — A headless server-rendered IMAGE of the map — the rendered view a viewer sees, as SVG or PNG, WITHOUT a browser (tk_0b6d3501 P2). - resolve_candidate — WHO holds or runs for WHAT — turn a candidate/officeholder name into their seat + next race. - resolve_map_comment — Mark a map comment resolved (closed), like resolving a Google-Docs comment — or reopen it with resolved:false. - resume_setup — CUSTOMER SETUP — the authoritative state of a setup session after auth, checkout or reload: status, step, client type, setup_scope, geography, owner linkage. - revision_ladder — Revision ladder L2 as DATA (not a render): render-ready before/after delta so the CLIENT visualizes it. - save_calendar_scenario — Save a NAMED primary-calendar ordering as a first-class, diffable artifact. - scenario_handoff_bundle — One consolidated, machine-readable audit + handoff packet for a scenario, so a teammate or a future AI session can resume without reconstructing context from many calls. - search_candidates — BROWSE the canonical candidate registry WITHOUT a name — the nameless companion to resolve_candidate (which requires a name). - senate_path_to_majority — Calculate a deterministic Senate path to majority from the active user-controlled scenario's modeled margins, carryover assumptions, protected seats, and target control rule. - set_ballot_order — BALLOT DESIGN — record each candidate's printed ballot POSITION (and an optional per-candidate confusion/roll-off assumption) for a simulation+level roster, so same-name and… - set_geo_knowledge — Write your workspace CUSTOM overlay for a geography — campaign-specific notes, target shares, turf intel, local relationships, assumptions — layered ON TOP of (and able to… - set_view — Set the active scenario view and selected map context: race stage, calendar playhead, geography grain, result source, selected feature, camera, map theme, and rail. - start_setup — CUSTOMER SETUP — create a durable server-side setup session from an acquisition choice: client_type (team size/use) plus setup_scope (race|county|district|state|multi),… - start_subscription — BILLING — begin a paid subscription. - tipping_point — Identify the tipping-point race and nearby high-leverage races in the active user-controlled scenario, using its modeled margins and canonical version context. Run the primaries: - clear_dem_calendar — Discard the simulation's user-defined Democratic calendar and revert to the default 2024-based Dem calendar. - clear_primary_shares — Remove a state's primary vote shares for a party (un-model that contest). - define_dem_calendar — Define a user-authored Democratic primary calendar order and dates for this simulation. - list_primary_calendar — Read the 2028 primary calendar with source dates, schedule certainty, modeled delegate coverage, missing jurisdictions, and threshold basis. - roll_up_primary — The running delegate count — OR, for a race-scoped downballot sim, that race's own share rollup. - set_primary_asof — Move the calendar playhead — the point in the primary calendar "as of" which to view the race on the map/chart. - set_primary_candidates — Define the candidate field for a party's presidential primary on this simulation (the GOP/Dem contenders). - set_primary_county_shares — Model a party's presidential primary at COUNTY level: set one county's candidate vote shares within a state's primary. - set_primary_demo_levers — Set a candidate's GLOBAL DEMOGRAPHIC DIALS in a primary — how many points to shift them among a voter group across the whole district/state. - set_primary_grain_pref — Pin which modeling grain DRIVES a state in a party's presidential primary — i.e. - set_primary_precinct_shares — Model a party's presidential primary at PRECINCT level — the finest grain. - set_primary_shares — Set a party's presidential-primary vote shares — one state, or MANY states in a single call. 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 immutable versions. - list_scenario_versions — The append-only version chain for a scenario, newest last, with per-version summary + top_line. - 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 the exact configuration) plus the hash… Roll up the outcome: - compare_simulations — Compare two simulations. - 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 baseline-to-model winner changes. - roll_up_race — Roll up precincts to a race outcome under the current simulation. - roll_up_state_races — Roll up every user-modeled race at one office level within a state, returning current modeled winners and margins from the canonical scenarios. - senate_control — Compute Senate control for a cycle using the real class calendar. - set_compare_paths — Generate a two-path comparison that the browser renders side-by-side. Plan a campaign: - compute_vote_goal — Calculate the deterministic win number and remaining vote gap for the active user-controlled scenario. - get_campaign_context — Load one campaign geography's state of play: canonical modeled/baseline context and the linked campaign plan, with source and as-of provenance. - target_list — CAMPAIGN OPERATIONS — read or reorder the active scenario's shared War Room target posts. - target_precincts — Return structured precinct model rows: precinct_id, name, county, county_fips, baseline_share, modeled_share, ballots_est, overridden, and gap_to_goal. Find your way (discovery & trust): - data_provenance — GOVERNANCE — read the supported 2024 presidential mixed-grain baseline, boundary identities, and user-authored scenario provenance. - get_catalog — DISCOVERY — browse workflow/category groups, search tool names and descriptions, or fetch one complete schema and AI guide with tool. - get_usage — OBSERVABILITY — session usage meter: total api_calls (every tool invocation since this server session began), distinct tools used, a by_category breakdown, and the per-tool… - help — Orient an AI client to campaign onboarding through get_campaign_onboarding, user-controlled election modeling, candidate and presidential-primary workflows, supported… - list_events — WITNESS STREAM (EM-116) — replay the ordered server-side event log of every tool-call (a running then a done event each, carrying category, latency_ms, args_digest,… - verify_audit — WITNESS AUDIT (EM-116) — re-verify the immutable, content-hashed audit chain of a scenario's committed versions (commit_version is the append-only hash-stamped write). Explore places & ballots: - election_calendar — The election planning calendar. - get_geography — Boundary reference, children, and a demographic summary (county grain — ACS 2023; states and districts return boundary + identity only) for a canonical geo_id (us, us-ca,… - list_contests — Discover contests for a geography and election cycle. - list_districts — List every district at a given race level. - list_features — List the geographic features (counties, states, districts, etc.) for a given level. - list_levels — List the office levels available to a user-controlled scenario, with typed modelability and coverage status for each level. - precincts_in_district — Page precincts whose centroid falls inside the district boundary, in precinct-id order. - resolve_geography — Turn a place name or shorthand into its canonical geo_id — resolve natural-language or structured location input. Publish & share: - get_shapes — Return state, county, district, or precinct boundaries for the active election model, optionally colored by canonical scenario metrics or the validated 2024 presidential baseline. - revoke_share — Revoke a previously-minted public share token. - share_simulation — Mint a public, read-only link to the exact canonical scenario/version. ## Tool profiles - Keyless sessions receive the retained Core modeling catalog. - Authenticated sessions receive Workbench: Core plus people, tasks, War Room, files, workspaces, and campaign operations. - get_catalog searches the same authorized catalog returned by tools/list. ## 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 ## Access Keyless Core is a read/simulate sandbox. Sign in for durable Workbench scenarios, campaign operations, people, tasks, files, and contextual War Room collaboration. The server-provided plan catalog is the authority for current entitlements and pricing: https://www.electionsmcp.com/api/plan-catalog ## Links - App: https://www.electionsmcp.com/ - Plans & demo: https://www.electionsmcp.com/pricing - Browse 2028 races: https://www.electionsmcp.com/2028 - MCP endpoint + connection guide: https://www.electionsmcp.com/mcp - Baseline provenance: call data_provenance({source:"2024_president_mixed_grain"})