openfec-mcp-server

Openfec Search Candidates

openfec_search_candidates

Read-onlyIdempotent

Find federal candidates by name, state, office, party, or cycle. Retrieve a specific candidate by FEC ID with financial totals. Candidate IDs start with H (House), S (Senate), or P (President) followed by exactly eight letters or digits.

Input Schema

TableJSON Schema

Name	Required	Description
`page`	No	Search-results page number (1-indexed). Defaults to 1 on the search path.
`cycle`	No	Two-year election cycle (even year, e.g., 2024).
`party`	No	Three-letter party code (e.g., DEM, REP, LIB).
`query`	No	Full-text candidate name search.
`state`	No	Two-letter US state code (e.g., AZ, CA).
`office`	No	Filter by office: H=House, S=Senate, P=President.
`district`	No	Two-digit district number for House candidates.
`per_page`	No	Search results per page. Defaults to 20 on the search path.
`candidate_id`	No	FEC candidate ID: H, S, or P followed by exactly eight letters or digits (e.g., P00003392, H2CO07170). Get IDs from openfec_search_candidates results. When provided, returns a single candidate with full detail.
`election_year`	No	Specific election year the candidate ran in.
`include_totals`	No	Include financial totals (receipts, disbursements, cash on hand). Defaults to true when fetching by candidate_id.
`candidate_status`	No	Candidate status: C=present, F=future, N=not yet, P=prior.
`has_raised_funds`	No	Only candidates whose committee has received receipts.
`incumbent_challenge`	No	Incumbent status: I=incumbent, C=challenger, O=open seat.

Output Schema

TableJSON Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Guidance when the response carries no candidates: how to broaden a search that matched nothing, or which requested position ran out when candidates did match.
`totals`	No	Financial totals (receipts, disbursements, cash_on_hand) when include_totals is true. One row per candidate per cycle.
`candidates`	No	Candidate result set; one record per match.
`pagination`	No	Page-based pagination metadata.
`totalCount`	No	Total matching candidates before pagination.
`missing_totals`	No	Candidates whose financial totals were not retrieved because the totals fetch hit its page cap. Re-query each one on its own with candidate_id to get its totals.
`search_criteria`	No	Echo of the search filters this call applied, as the server parsed them, minus paging arguments. Always present — compare it against what you sent to confirm every filter was honoured.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedSep 22, 2026

changedOutput schema / properties / notice / description

Previous value: -"Guidance when no candidates matched — echoes filters and suggests how to broaden."New value: +"Guidance when the response carries no candidates: how to broaden a search that matched nothing, or which requested position ran out when candidates did match."

addedOutput schema / properties / pagination / properties / count_is_approximate

Added value: +{
+  "description": "True when OpenFEC reports this count as an estimate rather than a tally, which it does on its highest-volume datasets. Absent means the count is a tally. An estimated count — and the pages derived from it — can be off by a wide margin; treat it as an order of magnitude, not a figure to quote.",
+  "type": "boolean"
+}

Changed1 schema field changedSep 19, 2026

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `candidate_not_found`: Single-candidate lookup by candidate_id returned no record `inputs_not_applicable_to_id_lookup`: A direct candidate_id lookup includes search-only inputs, or totals-only scope while include_totals is false Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `candidate_not_found`: Single-candidate lookup by candidate_id returned no record. `inputs_not_applicable_to_id_lookup`: A direct candidate_id lookup includes search-only inputs, or totals-only scope while include_totals is false. Other values are possible when a failure originates below the handler."

Changed7 schema fields changedAug 31, 2026

changedInput schema / properties / candidate_id / description

Previous value: -"FEC candidate ID (e.g., P00003392, H2CO07170). Get IDs from openfec_search_candidates results. When provided, returns a single candidate with full detail."New value: +"FEC candidate ID: H, S, or P followed by exactly eight letters or digits (e.g., P00003392, H2CO07170). Get IDs from openfec_search_candidates results. When provided, returns a single candidate with full detail."

removedInput schema / properties / page / default
```
Removed value: -1
```

changedInput schema / properties / page / description

Previous value: -"Page number (1-indexed)."New value: +"Search-results page number (1-indexed). Defaults to 1 on the search path."

removedInput schema / properties / per_page / default
```
Removed value: -20
```

changedInput schema / properties / per_page / description

Previous value: -"Results per page."New value: +"Search results per page. Defaults to 20 on the search path."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `candidate_not_found`: Single-candidate lookup by candidate_id returned no record Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `candidate_not_found`: Single-candidate lookup by candidate_id returned no record `inputs_not_applicable_to_id_lookup`: A direct candidate_id lookup includes search-only inputs, or totals-only scope while include_totals is false Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "candidate_not_found"
-]New value: +[
+  "candidate_not_found",
+  "inputs_not_applicable_to_id_lookup"
+]

Changed6 schema fields changedAug 25, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "candidates",
+      "pagination",
+      "search_criteria",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `candidate_not_found`: Single-candidate lookup by candidate_id returned no record Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "candidate_not_found"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "candidates",
-  "pagination",
-  "search_criteria",
-  "totalCount"
-]

Changed2 schema fields changedJul 26, 2026

changedOutput schema / properties / search_criteria / description

Previous value: -"Echo of the search filters that produced this result set. Populated when results are empty to help diagnose why nothing matched."New value: +"Echo of the search filters this call applied, as the server parsed them, minus paging arguments. Always present — compare it against what you sent to confirm every filter was honoured."

changedOutput schema / required

Previous value: -[
-  "candidates",
-  "pagination",
-  "totalCount"
-]New value: +[
+  "candidates",
+  "pagination",
+  "search_criteria",
+  "totalCount"
+]

Changed2 schema fields changedJul 26, 2026

addedOutput schema / properties / missing_totals

Added value: +{
+  "description": "Candidates whose financial totals were not retrieved because the totals fetch hit its page cap. Re-query each one on its own with candidate_id to get its totals.",
+  "items": {
+    "description": "FEC candidate ID with no totals row in this response.",
+    "type": "string"
+  },
+  "type": "array"
+}

changedOutput schema / properties / totals / description

Previous value: -"Financial totals (receipts, disbursements, cash_on_hand) when include_totals is true."New value: +"Financial totals (receipts, disbursements, cash_on_hand) when include_totals is true. One row per candidate per cycle."

Changed1 schema field changedJun 8, 2026
- removedInput schema / properties / candidate_id / pattern
```
Removed value: -"^[HSP][0-9A-Z]+$"
```

Changed3 schema fields changedMay 30, 2026

addedOutput schema / properties / notice

Added value: +{
+  "description": "Guidance when no candidates matched — echoes filters and suggests how to broaden.",
+  "type": "string"
+}

addedOutput schema / properties / totalCount

Added value: +{
+  "description": "Total matching candidates before pagination.",
+  "type": "number"
+}

changedOutput schema / required

Previous value: -[
-  "candidates",
-  "pagination"
-]New value: +[
+  "candidates",
+  "pagination",
+  "totalCount"
+]

Changed2 schema fields changedMay 27, 2026

changedInput schema / properties / candidate_id / description

Previous value: -"FEC candidate ID (e.g., P00003392, H2CO07170). When provided, returns a single candidate with full detail."New value: +"FEC candidate ID (e.g., P00003392, H2CO07170). Get IDs from openfec_search_candidates results. When provided, returns a single candidate with full detail."

addedInput schema / properties / candidate_id / pattern
```
Added value: +"^[HSP][0-9A-Z]+$"
```

Changed13 schema fields changedMay 8, 2026

addedInput schema / properties / page / default
```
Added value: +1
```

changedInput schema / properties / page / description

Previous value: -"Page number (1-indexed). Default 1."New value: +"Page number (1-indexed)."

addedInput schema / properties / page / maximum
```
Added value: +9007199254740991
```
addedInput schema / properties / page / minimum
```
Added value: +1
```

changedInput schema / properties / page / type

Previous value: -"number"New value: +"integer"

addedInput schema / properties / per_page / default
```
Added value: +20
```

changedInput schema / properties / per_page / description

Previous value: -"Results per page. Default 20, max 100."New value: +"Results per page."

addedInput schema / properties / per_page / maximum
```
Added value: +100
```
addedInput schema / properties / per_page / minimum
```
Added value: +1
```

changedInput schema / properties / per_page / type

Previous value: -"number"New value: +"integer"

changedOutput schema / properties / candidates / description

Previous value: -"Candidate records with candidate_id, name, party, state, office, cycles, etc."New value: +"Candidate result set; one record per match."

changedOutput schema / properties / candidates / items / description

Previous value: -"A candidate record (candidate_id, name, party, state, office, cycles, ...)."New value: +"Candidate record; common keys include candidate_id, name, party, state, office, and cycles."

changedOutput schema / properties / totals / items / description

Previous value: -"A per-cycle financial totals row for a candidate committee."New value: +"Per-cycle financial totals row for a candidate committee."

Changed2 schema fields changedApr 24, 2026

addedOutput schema / properties / candidates / items / description

Added value: +"A candidate record (candidate_id, name, party, state, office, cycles, ...)."

addedOutput schema / properties / totals / items / description

Added value: +"A per-cycle financial totals row for a candidate committee."

Changed6 schema fields changedApr 21, 2026
- addedOutput schema / properties / candidates / items / properties
```
Added value: +{}
```
- removedOutput schema / properties / candidates / items / propertyNames
```
Removed value: -{
-  "type": "string"
-}
```
- addedOutput schema / properties / search_criteria / properties
```
Added value: +{}
```
- removedOutput schema / properties / search_criteria / propertyNames
```
Removed value: -{
-  "type": "string"
-}
```
- addedOutput schema / properties / totals / items / properties
```
Added value: +{}
```
- removedOutput schema / properties / totals / items / propertyNames
```
Removed value: -{
-  "type": "string"
-}
```
First observedApr 13, 2026

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds the ID-prefix rule and that a specific ID returns financial totals, but much of this is also present in the schema; no rate limits, pagination behavior, or edge-case semantics are disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences front-load the core search behavior, then add the important ID-lookup variant and ID format rule. There is no filler or redundant explanation; every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 14 parameters, a fully described schema, and an output schema, the description gives enough high-level orientation: what candidates are, how to filter, and how to do exact ID lookup. It could add a brief note on when the ID-lookup path is preferable, but the schema and annotations fill most operational gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents all 14 parameters. The description summarizes the primary filter dimensions and candidate ID format but adds no semantic detail beyond a concise overview; per the high-coverage rule, baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verbs ('Find', 'Retrieve') on a clear resource ('federal candidates') and names the main filter dimensions and the ID-lookup mode. It is unmistakably a candidate search, but it does not explicitly contrast itself with sibling tools like openfec_search_committees, so it stops just short of full sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear search contexts: filter by candidate attributes or fetch a single candidate by FEC ID, and it flags the financial-totals case. There are no exclusions or named alternatives, so the agent is not told when to prefer this over openfec_search_committees, but the intended invocation is explicit enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All openfec-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.