Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@cdgmcp What bills were introduced in the House yesterday?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server that exposes a Congress.gov-style legislative GraphQL API to MCP clients (such as VS Code, Claude Desktop, or other agents). It provides high-level tools for querying bills, actions, committee activities and cosponsors, plus a raw GraphQL escape hatch for advanced queries.
Tool | Description |
| Search/list bills with filters (congress, chamber, type, title, latest action, dates, sponsor). |
| Fetch a single bill's full details, with optional actions, cosponsors, committee activities, titles and text versions. |
| Find committee referrals/activities and their related bills. |
| Search the legislative action history (e.g. "Passed House", "Became Public Law"). |
| Search cosponsorship records across bills. |
| Fetch any object directly by its Relay global |
| Run an arbitrary read-only GraphQL query (mutations rejected). |
The API is built with Hot Chocolate 16.2.0 and follows Relay conventions. The
search tools are connection-based: each returns pageInfo.endCursor, which you
can pass back as the after argument to fetch the next page.
URI | Description |
| The live GraphQL schema (SDL). |
| Data model and usage guide. |
| The configured GraphQL endpoint. |
Related MCP server: CongressMCP-full
What bills have been recently introduced in the House or Senate?
What bills have passed the House or Senate and became law recently?
What bills have been referred to the Commerce Committee recently?
Of the bills referred to the Agriculture Committee, which cosponsors recur across them?
The GraphQL endpoint defaults to http://dotnet10-dev:5208/graphql/. Override
it with the CDG_GRAPHQL_ENDPOINT environment variable.
npm install
npm run build
npm start # or: node dist/index.jsFor development (no build step) use:
npm run dev # runs src/index.ts via tsxAdd to your .vscode/mcp.json (or user mcp.json):
{
"servers": {
"cdgmcp": {
"command": "node",
"args": ["${workspaceFolder}/cdgmcp/dist/index.js"],
"env": {
"CDG_GRAPHQL_ENDPOINT": "http://dotnet10-dev:5208/graphql/"
}
}
}
}The server communicates over stdio.
This is supposed to be a standalone testing something, but I haven't seen it work.
HOST=0.0.0.0 npx @modelcontextprotocol/inspector node dist/index.jsFetch a single bill's full details. Identify it either by cdgId or by the combination of congress + billType + number. Optionally include related actions, cosponsors, committee activities, titles and text versions.
| Name | Required | Description | Default |
|---|---|---|---|
| cdgId | No | The bill's cdgId. Provide this OR congress+billType+number. | |
| congress | No | Congress number, e.g. 119. | |
| billType | No | Bill type code, e.g. HR, S, HJRES. | |
| number | No | Bill number, e.g. 1234. | |
| includeActions | No | Include the action history. | |
| includeCosponsors | No | Include the list of cosponsors. | |
| includeCommitteeActivities | No | Include committee referral/activity history. | |
| includeTitles | No | Include all titles for the bill. | |
| includeTextVersions | No | Include text version documents. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not disclose any behavioral traits such as side effects, authentication needs, rate limits, or error handling. The description only states what the tool does, not how it behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, concise, and front-loaded with the main purpose. Every part adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description should hint at return fields. It says 'full details' but does not specify what that includes beyond the optional inclusions. With 9 parameters, more detail on the response would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameter descriptions already exist. The description adds context on the identification options (cdgId vs congress+billType+number) and optional booleans, but this largely reinforces schema info without adding new meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches a single bill's full details, and specifies two distinct identification methods. This is specific and distinguishes from sibling tools like search_bills, which is for listing multiple bills.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to identify the bill (cdgId or congress+billType+number) and mentions optional inclusions. However, it does not explicitly state when to use this versus alternatives like search_actions or search_cosponsors, though context from sibling names implies when to use those.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch any object directly by its Relay global id (the opaque id field returned on Bills, Actions, CommitteeActivities, Cosponsors, BillTitles and TextVersions). Returns the concrete type's fields. Use this when you already have a node's global id; to look a bill up by congress/type/number use get_bill instead.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The Relay global object id (the `id` field). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must cover behavior. It mentions return type ('concrete type's fields') but does not disclose behavior on invalid IDs, error handling, or rate limits, leaving gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words, key information front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool with no output schema, the description adequately covers purpose, usage, and parameter semantics, though it omits potential failure modes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a basic description. The tool description adds context about the 'id' being an opaque Relay global ID from specific types, which goes beyond the schema's minimal description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch any object') and the resource ('by Relay global id'), and distinguishes it from sibling tool get_bill by specifying when to use each.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('when you already have a node's global id') and when not to ('to look a bill up by congress/type/number use get_bill instead'), providing a clear alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute an arbitrary read-only GraphQL query against the legislative API. Use this for complex questions the specialised tools do not cover (e.g. cross-referencing committee activities with bill cosponsors). Read the 'cdg://schema' resource for the full schema. Mutations are rejected.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | A GraphQL query document. Must be a query (no mutations). | |
| variables | No | Optional variables object for the query. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It clearly states that the tool is read-only and that mutations are rejected. This is key behavioral information. However, it does not mention authentication, rate limits, or error handling, which would be helpful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose. It includes a usage example and a resource reference. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a raw GraphQL tool, the description lacks information about the return format or response structure (no output schema exists). It does mention reading the input schema but not the output. The description is adequate but incomplete for a tool that returns arbitrary data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents both parameters (query and variables) adequately. The tool description does not add significant meaning beyond confirming that query must not be a mutation. It does not elaborate on the variables parameter structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Execute' and identifies the resource as 'read-only GraphQL query against the legislative API'. It clearly distinguishes itself from sibling tools by stating 'Use this for complex questions the specialised tools do not cover', making its purpose and scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use (complex questions not covered by specialized tools) and provides an example. It does not explicitly state when not to use, but the context implies that specialized tools should be preferred. The reference to reading the schema resource provides further guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the legislative action history across bills. Use this to find events like 'Passed House', 'Passed Senate', 'Became Public Law', or to inspect actions by type/code. Each result includes the related bill.
| Name | Required | Description | Default |
|---|---|---|---|
| textContains | No | Substring to match within the action text, e.g. 'Passed House', 'Became Public Law', 'Signed by President'. | |
| actionType | No | Exact action type, e.g. 'Floor', 'BecameLaw', 'IntroReferral'. | |
| actionCode | No | Exact action code. | |
| actionDateAfter | No | Only actions on/after this date (YYYY-MM-DD). | |
| actionDateBefore | No | Only actions on/before this date (YYYY-MM-DD). | |
| sortBy | No | Field to sort by. Default: actionDate. | |
| sortOrder | No | Sort direction. Default: DESC (newest first). | |
| limit | No | Max results to return (1-50). Default 10. | |
| after | No | Relay pagination cursor. Pass the `pageInfo.endCursor` from a previous result to fetch the next page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description discloses that results include related bill but does not explicitly state read-only nature or other behavioral traits like rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences front-loaded with purpose, efficient and no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main use cases but omits pagination explanation and default sort order; no output schema requires more detail on return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good descriptions; description adds value via examples but does not detail all parameters beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches legislative action history across bills, uses specific verb 'Search', and distinguishes from siblings like search_bills by focusing on actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides concrete examples of when to use (e.g., find 'Passed House'), but lacks explicit comparison to alternatives or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search and list bills/resolutions with flexible filters. Use this for questions like 'bills recently introduced in the House', 'bills that became law recently' (latestActionContains: 'Became Public Law'), or 'bills that passed the Senate' (latestActionContains: 'Passed Senate'). Results are paginated; increase 'limit' (max 50) for more.
| Name | Required | Description | Default |
|---|---|---|---|
| congress | No | Congress number, e.g. 119 for the 119th Congress. | |
| billType | No | Bill type code: HR, S, HJRES, SJRES, HCONRES, SCONRES, HRES, SRES. | |
| originChamber | No | Chamber where the bill originated. | |
| titleContains | No | Case-sensitive substring to match within the bill title. | |
| latestActionContains | No | Substring to match within the latest action text. Examples: 'Became Public Law', 'Passed House', 'Passed Senate', 'Referred to the Committee'. | |
| introducedAfter | No | Only bills introduced on/after this date (YYYY-MM-DD). | |
| introducedBefore | No | Only bills introduced on/before this date (YYYY-MM-DD). | |
| sponsorState | No | Two-letter state code of the bill sponsor, e.g. 'CA'. | |
| sponsorParty | No | Party of the bill sponsor, e.g. 'R', 'D', 'I'. | |
| sponsorBioguideId | No | Bioguide ID of the bill sponsor. | |
| sortBy | No | Field to sort by. Default: introducedDate. | |
| sortOrder | No | Sort direction. Default: DESC (newest first). | |
| limit | No | Max results to return (1-50). Default 10. | |
| after | No | Relay pagination cursor. Pass the `pageInfo.endCursor` from a previous result to fetch the next page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It mentions pagination and limit max, but does not state read-only nature or any side effects. Adequate but could be more explicit about behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus examples; front-loaded with purpose, no fluff. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 14 parameters, no required, and no output schema, the description covers the essential usage and pagination. It could mention the return format, but is fairly complete for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good descriptions; the description adds value through examples (e.g., latestActionContains: 'Became Public Law') but does not significantly augment parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search and list bills/resolutions with flexible filters' and provides concrete query examples, distinguishing this from sibling tools like search_actions (actions on bills) and get_bill (single bill).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly gives usage examples (e.g., 'bills recently introduced in the House') and shows parameter combinations. It does not explicitly say when not to use or name alternatives, but the examples are clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find committee activities (e.g. referrals) and the bills they relate to. Use this for questions like 'bills referred to the Commerce Committee recently' (committeeNameContains: 'Commerce', activityNameContains: 'Referred'). Each result includes the related bill summary.
| Name | Required | Description | Default |
|---|---|---|---|
| committeeNameContains | No | Substring to match within the committee name, e.g. 'Commerce', 'Agriculture', 'Judiciary'. | |
| committeeCode | No | Exact committee system code, e.g. 'HSAG' or 'HSIF'. | |
| chamber | No | Chamber, e.g. 'House' or 'Senate'. | |
| activityNameContains | No | Substring to match within the activity name, e.g. 'Referred', 'Markup', 'Discharged', 'Reported'. | |
| sortBy | No | Field to sort by. Default: activityTimestamp. | |
| sortOrder | No | Sort direction. Default: DESC (newest first). | |
| limit | No | Max results to return (1-50). Default 10. | |
| after | No | Relay pagination cursor. Pass the `pageInfo.endCursor` from a previous result to fetch the next page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose all behavioral traits. It mentions that each result includes a related bill summary, which is useful. However, it does not cover other aspects like pagination behavior (despite the 'after' parameter), rate limits, or whether the tool is read-only. The description is adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long and well-structured. The first sentence states the core purpose, and the second gives a practical example. Every sentence serves a clear purpose with no redundant or vague wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 8 optional parameters and no output schema, the description covers the essential context: what the tool does, a typical query example, and the nature of the results (includes bill summary). It could mention pagination or default sorting, but the provided information is sufficient for basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes all 8 parameters with 100% coverage. The description adds value by providing a concrete usage example mapping 'committeeNameContains' and 'activityNameContains' to a query, which clarifies how to use these parameters together.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds committee activities and their related bills, providing a specific verb-resource pair. The example with 'committeeNameContains' and 'activityNameContains' distinguishes it from siblings like search_bills or search_actions, which focus on other aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a concrete example of when to use it (e.g., 'bills referred to the Commerce Committee recently'), making the usage context clear. However, it does not explicitly mention when not to use it or compare with sibling tools beyond the implicit differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search bill cosponsorship records across bills. Useful for finding all the bills a member has cosponsored, or analysing cosponsorship by state/party. To get the cosponsors of a specific bill, prefer get_bill with includeCosponsors: true.
| Name | Required | Description | Default |
|---|---|---|---|
| bioguideId | No | Bioguide ID of the cosponsoring member. | |
| fullNameContains | No | Substring to match within the member's full name. | |
| state | No | Two-letter state code, e.g. 'TX'. | |
| party | No | Party, e.g. 'R', 'D', 'I'. | |
| isOriginalCosponsor | No | Filter to original cosponsors only (true) or later ones (false). | |
| sortBy | No | Field to sort by. Default: sponsorshipDate. | |
| sortOrder | No | Sort direction. Default: DESC. | |
| limit | No | Max results to return (1-50). Default 10. | |
| after | No | Relay pagination cursor. Pass the `pageInfo.endCursor` from a previous result to fetch the next page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not state that the tool is read-only, mention any side effects, authentication requirements, rate limits, or pagination behavior beyond the 'after' parameter. The description is minimal and lacks transparency about the nature of the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, with two sentences that front-load the purpose and provide usage guidance. No irrelevant information, every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 9 parameters and no output schema, the description provides a general purpose and use cases but does not describe the output structure or return format. It is moderately complete but could be improved by mentioning typical query results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add significant extra meaning to the parameters beyond what the schema provides, though it implies using bioguideId for finding a member's cosponsored bills.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search bill cosponsorship records across bills' and distinguishes from sibling tool get_bill which retrieves cosponsors for a specific bill. The verb 'search' and resource 'cosponsorship records' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool (to find all bills a member cosponsored or analyze by state/party) and explicitly states an alternative: 'To get the cosponsors of a specific bill, prefer get_bill with includeCosponsors: true.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct entity or operation: bill lookup, generic node fetch, arbitrary GraphQL queries, and searches for actions, bills, committees, and cosponsors. No two tools have overlapping purposes.
Most tools follow a clear verb_noun pattern (e.g., get_bill, search_actions), but graphql_query breaks this by using a noun_noun format. Overall naming is still consistent and predictable.
Seven tools is well-scoped for the legislative domain, covering core entities (bills, actions, committees, cosponsors) plus a generic query tool. Not too many or too few.
The tool set covers bill retrieval, search, and relational data (actions, committees, cosponsors). The graphql_query tool fills any gaps, making the surface effectively complete for read-only legislative data access.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Access U.S. congressional data - bills, votes, members, committees - via MCP.
An MCP server that provides congressional transcripts
GovTrack MCP — federal US Congress data (free, no auth)
Congress MCP — US Congress data via GovTrack API (free, no auth required)
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/adathouse/cdgmcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
