# FOIA.gov MCP > FOIA.gov provides direct access to US government transparency data via Freedom of Information Act records. Use this MCP to discover agency components, pull detailed metadata for specific departments, generate compliance forms, and retrieve annual reports in structured XML format. It lets your AI client interact with the complex structure of federal agencies using natural conversation. ## Overview - **Category:** knowledge-management - **Price:** Free - **Tags:** transparency, public-records, legal-data, agency-reporting, document-management ## Description This connector helps you cut through the bureaucracy of US government data. Instead of spending hours navigating massive websites, figuring out which department holds what records, or manually downloading incompatible PDFs, you can talk to your agent and get precise data structures back. It lets you list all the components of a federal agency—from the Department of Justice down to specific sub-sections. Need to know exactly what fields are required to submit a request for one component? It fetches that official form structure instantly. You can also pull historical metrics, like annual reports in XML format, which is gold for large data analysis. If you're building an automated research pipeline, Vinkius makes sure this MCP is accessible from your favorite AI client, giving you structured government records without the friction. ## Tools ### get_agency_component_request_form Fetches the precise structure and required fields for a FOIA request form specific to one component. ### get_agency_component Retrieves deep metadata for a specific component using its unique UUID. ### get_annual_report_xml Downloads the official annual report data for an agency in structured XML format, based on the year provided. ### list_agency_components Lists all available FOIA agency components, letting you filter the search results by title or abbreviation. ## Prompt Examples **Prompt:** ``` List all FOIA agency components and include their parent agency names. ``` **Response:** ``` I've retrieved the list of agency components. There are several hundred components across departments like the DOJ, DOD, and DHS. Would you like to filter this list by a specific keyword or agency abbreviation? ``` **Prompt:** ``` Get the FOIA request form structure for the agency component with UUID '654321-abc-...'. ``` **Response:** ``` I have the form structure for that component. It requires fields such as 'Description of Records', 'Fee Waiver Request', and 'Expedited Processing'. I can provide the specific JSON schema for these fields if you need to build a submission. ``` **Prompt:** ``` Fetch the 2021 annual report XML for the DOJ. ``` **Response:** ``` I've successfully retrieved the 2021 Annual FOIA Report for the Department of Justice in XML format. The report includes detailed statistics on requests received, processed, and pending, as well as processing times. ``` ## Capabilities ### Discover all agency parts List and filter every component within the FOIA system by title or abbreviation. ### Get specific component details Fetch deep metadata for a known agency part using its unique identification code (UUID). ### Retrieve request form structure Pull the exact required fields and format needed to build an official FOIA submission for any component. ### Fetch historical annual reports Download agency transparency metrics from yearly reports in XML format, ready for data processing. ## Use Cases ### Investigating a specific department's mandate A researcher needs to know if the National Weather Service (NWS) falls under the Department of Commerce. Instead of clicking through confusing directory pages, they ask their agent to `list_agency_components` and filter by 'weather.' The system instantly returns the component details for NWS. ### Building a compliant form generator A legal team needs to build an internal tool that accepts FOIA requests. They use `get_agency_component_request_form` on a target component UUID, which returns the JSON schema needed for their submission validation layer. ### Comparing departmental spending over time A data analyst wants to compare Department A's transparency metrics against Department B's from 2019-2023. They use `get_annual_report_xml` repeatedly for each department and year, getting clean XML files ready for a single spreadsheet import. ### Mapping an unknown agency UUID A journalist has found a strange component UUID in a public document but doesn't know what it belongs to. They feed the ID into `get_agency_component`, and the system returns all the associated metadata, including its parent department. ## Benefits - Stop guessing the right web page. Use `list_agency_components` to quickly see every component that handles public records, letting you narrow down your search immediately. - Avoid compliance errors. If you need to file a request, use `get_agency_component_request_form`. It gives you the exact required JSON schema for that specific agency part. - Analyze large datasets fast. Pulling annual reports via `get_annual_report_xml` provides raw XML metrics, which is much better than wading through image-heavy PDFs. - Pinpoint missing data points. Need to know exactly what a department does? Run the component details using `get_agency_component` for full metadata on any UUID. - Saves research time. Instead of opening 20 different government websites, you ask your agent and get structured answers from one place. ## How It Works The bottom line is: you skip the website navigation and get directly to actionable government data. 1. First, connect your AI client to this MCP and provide the required FOIA.gov API key. 2. Tell your agent what you need—for example, 'List all components under DHS' or 'Get the 2021 annual report for DOJ'. 3. The MCP executes the request and sends back clean, structured data (JSON or XML) that your agent can use immediately. ## Frequently Asked Questions **How do I find out which agency components are available using list_agency_components?** You just tell your agent to run `list_agency_components`. It sends you a filtered, structured list of every component. You can then filter that output by title or abbreviation right away. **What is the difference between get_agency_component and getting annual report XML?** These two tools serve different purposes. `get_agency_component` gives you *metadata* (details about the component itself). `get_annual_report_xml` gives you actual historical *data* metrics for that agency over time. **Do I need a UUID to use get_agency_component_request_form?** Yes, you do. The form structure is specific to one component. You must provide the component's unique identifier (UUID) so the tool can fetch the correct compliance fields. **Can I pull annual report XML for multiple years at once?** The `get_annual_report_xml` tool fetches reports year by year. You'll need to run it sequentially, providing the specific UUID and each target year. **What happens if I run `list_agency_components` without proper authentication?** The call fails immediately with an API key error. You must first ensure your agent is configured with a valid FOIA.gov API key within the Vinkius catalog before running any tool. **If I use `get_agency_component` but provide an invalid UUID, what error do I receive?** You get a standard 404 Not Found status. The response body will confirm that the component ID does not exist in the registry, helping you correct your input quickly. **Does `list_agency_components` support filtering or pagination for large result sets?** Yes, the tool supports JSON API sparse fieldsets and inclusion parameters. You can pass these directly in your query to narrow results or handle thousands of records efficiently. **When using `get_agency_component_request_form`, what format is the returned schema?** It returns a structured JSON schema. This output details all required fields and their expected data types, making it easy for your agent to build compliance-ready submissions. **How can I find the specific requirements for filing a FOIA request with an agency?** You can use the `get_agency_component_request_form` tool with the agency's UUID. It will return the full structure of the form, including all required fields and instructions. **Is it possible to list all sub-components of a major government agency?** Yes. Use `list_agency_components` and you can include the parent agency information to filter or identify all components belonging to a specific department. **Can I access the raw annual transparency reports for data analysis?** Absolutely. The `get_annual_report_xml` tool allows you to fetch the official NIEM-standard XML reports for any agency and year (e.g., DOJ, 2021).