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

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. With include_totals, at most 35 candidates are requested when cycle or election_year scopes the totals and 5 when the totals span every cycle, keeping the response under a 100,000-byte budget. A page bounded below your request reports truncated and cap, and pagination.per_page echoes the size applied — page numbers count at that size, so continue with the next page number.
`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

Name	Required	Description
`cap`	No	The per_page this call applied in place of the one requested — the page-size ceiling for this tool and scope. Present only when truncated is true.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Rows in this page. Present only when truncated is true.
`notice`	No	Guidance when the response needs context: how to broaden a search that matched nothing, which requested position ran out when candidates did match, or that the page was bounded below the per_page requested and how to continue.
`totals`	No	Financial totals (receipts, disbursements, cash_on_hand) when include_totals is true. One row per candidate per cycle.
`truncated`	No	True when this page holds fewer rows than the per_page requested because a full page would exceed the 100,000-byte response budget, and more rows remain. Absent on a complete page, including a naturally short last page.
`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.

Changed5 schema fields changedSep 24, 2026

changedInput schema / properties / per_page / description

Previous value: -"Search results per page. Defaults to 20 on the search path."New value: +"Search results per page. Defaults to 20 on the search path. With include_totals, at most 35 candidates are requested when cycle or election_year scopes the totals and 5 when the totals span every cycle, keeping the response under a 100,000-byte budget. A page bounded below your request reports truncated and cap, and pagination.per_page echoes the size applied — page numbers count at that size, so continue with the next page number."

addedOutput schema / properties / cap

Added value: +{
+  "description": "The per_page this call applied in place of the one requested — the page-size ceiling for this tool and scope. Present only when truncated is true.",
+  "type": "number"
+}

changedOutput schema / properties / notice / description

Previous 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."New value: +"Guidance when the response needs context: how to broaden a search that matched nothing, which requested position ran out when candidates did match, or that the page was bounded below the per_page requested and how to continue."

addedOutput schema / properties / shown

Added value: +{
+  "description": "Rows in this page. Present only when truncated is true.",
+  "type": "number"
+}

addedOutput schema / properties / truncated

Added value: +{
+  "description": "True when this page holds fewer rows than the per_page requested because a full page would exceed the 100,000-byte response budget, and more rows remain. Absent on a complete page, including a naturally short last page.",
+  "type": "boolean"
+}

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

A4/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds the useful behavioral note that fetching by candidate_id returns financial totals, but it does not go further into pagination, response truncation, or other runtime behavior; with annotations present, this level of added context is acceptable but not rich.

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?

The description is three sentences with no filler: purpose, special lookup mode, and ID format each earn their place. It is front-loaded with the most important action ('Find federal candidates') and remains compact despite a 14-parameter tool.

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 the rich schema (100% coverage) and output schema, the description does not need to document every parameter. It covers the core selection context, the two usage modes, and the non-obvious ID format. It could mention pagination behavior or the distinction between search results and full detail, but the schema already handles those, so the description is sufficiently complete for tool selection and invocation.

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 baseline is 3. The description's mention of filters and the FEC ID pattern largely repeats what the schema already documents (e.g., candidate_id format, office codes). It does not introduce meaningful new parameter semantics beyond reinforcing the ID format and the 'financial totals' behavior tied to include_totals.

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

Purpose5/5

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

The description specifies a concrete verb-resource pair ('Find federal candidates' and 'Retrieve a specific candidate by FEC ID') and enumerates the key search dimensions (name, state, office, party, cycle). This clearly distinguishes it from sibling search tools like openfec_search_committees and openfec_search_contributions, while also signaling a distinct by-ID lookup mode with financial totals.

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?

The description gives clear usage context: use it to search candidates across several filters or to fetch one candidate by ID with totals. It does not explicitly name alternative tools or state when not to use it, but the purpose statement and ID-format guidance are enough for an agent to select it appropriately among the candidate-related siblings.

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.

Openfec Search Candidates

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources