# São Paulo (Cidade) MCP > São Paulo (Cidade) MCP Server connects your AI agent directly to the official São Paulo Open Data Portal. It lets you search thousands of public datasets covering health, education, transport, and city finance in Brazil's largest metropolis. Your agent can run complex SQL queries on CSV-backed resources or map out specific city organizations using natural language prompts. ## Overview - **Category:** data-analytics - **Price:** Free - **Tags:** open-data, urban-data, public-administration, ckan, sql-query ## Description Your AI client connects directly to the official São Paulo Open Data Portal. This gives you access to thousands of public datasets covering everything from city finance and health metrics to education records and transportation routes across Brazil's biggest metropolis. **Discovering Datasets** Need data? You start by knowing what’s out there. Use `list_packages` to get a complete inventory of every dataset available in the portal. If you know what you're looking for, use `search_packages`; you can run searches across the entire catalog using keywords or specific criteria. To narrow your focus quickly, check `list_tags`, which gives you a list of common tags used across datasets, letting you browse related topics instantly. You can also see all available thematic groupings with `list_groups`. If you need to know more about those categories, run `get_group` for detailed information on any specific group. **Mapping the City Structure** Figuring out which government body owns a dataset is half the battle. You can get a list of every contributing city department—the secretariats—using `list_organizations`. If you need to know more about one of those departments, run `get_organization` to get its metadata, scope, and purpose. These tools help map out exactly where the data comes from. **Inspecting Data Packages** Before you query anything, you gotta check the structure. Use `list_packages` again if you need a list of all available datasets (packages). To get full context on one specific dataset, run `get_package`. This pulls all the detailed metadata for that entire package, including what resources and tags it uses. You can also use `get_resource` to inspect a file's metadata within a package; this lets you check formats and IDs before trying to read the data. **Running Queries on Data** When you’re ready to pull numbers, your agent handles it in two ways. For basic field checking, use `datastore_search`. This tool searches for a specific value or column name inside an already loaded dataset resource file. If you need complex filtering—like running a SELECT WHERE command—you run `datastore_search_sql`. This executes highly structured queries directly on the data contained in the resource files. This means your agent can first use `list_organizations` to find the department, then `get_package` to confirm the dataset structure, and finally use `datastore_search_sql` to pull out exactly what you need. The system manages all those steps, sending the final data back for you to read. ## Tools ### datastore_search_sql Runs complex, structured queries (SELECT WHERE) directly on the data contained in a resource. ### datastore_search Searches for a specific value or column name within an already loaded dataset resource file. ### list_groups Lists all thematic groups available in the portal, helping you categorize your search scope. ### get_group Retrieves detailed information about a specific thematic group or category of datasets. ### list_organizations Provides a list of every city department that contributes data to the open data portal. ### get_organization Gets metadata for a city department (secretariat) that publishes data, showing its scope and purpose. ### list_packages Lists all available datasets (packages) in the entire São Paulo data portal, giving you an inventory view. ### search_packages Searches the entire catalog for dataset packages using keywords or criteria. ### get_package Retrieves the full details of an entire dataset package, including associated resources and tags. ### get_resource Gets specific file metadata (the actual data resource) within a dataset package to check formats and IDs. ### list_tags Provides a list of common tags used across datasets, allowing you to browse related topics quickly. ## Prompt Examples **Prompt:** ``` Search for datasets about public transport in São Paulo. ``` **Response:** ``` I found several datasets related to public transport. The most relevant are 'Bilhete Único statistics' and 'Bus lines and stops'. Would you like to see the resources for one of these? ``` **Prompt:** ``` List all organizations that provide open data in the portal. ``` **Response:** ``` I've retrieved the list of organizations. There are over 50 entities, including 'Secretaria Municipal da Saúde', 'Secretaria Municipal de Educação', and 'SPTrans'. Which one should we explore? ``` **Prompt:** ``` Get the details for the dataset 'folha-de-pagamento'. ``` **Response:** ``` The dataset 'folha-de-pagamento' contains payroll information for city employees. It has 12 resources available, mostly in CSV and PDF formats. Would you like the ID of the latest CSV resource to query it? ``` ## Capabilities ### Search datasets by keywords or tags Find relevant data packages across the entire city portal using `search_packages`. ### Execute complex SQL queries on stored data Run specific, filtered commands against a dataset's resources using `datastore_search_sql`. ### Map city organizations and departments List all government bodies or secretariats that publish open data via `list_organizations` and `get_organization`. ### Retrieve full dataset metadata Get detailed information on any specific dataset using the `get_package` tool, including its structure and resource list. ### Inspect data fields within a file Search for a specific value or column name inside an already loaded dataset resource using `datastore_search`. ## Use Cases ### Auditing public spending on infrastructure A journalist needs to track how much was spent on road maintenance vs. public transport over five years. They ask their agent: 'List all organizations involved in transport and give me the datasets.' The agent uses `list_organizations` and then runs targeted queries using `datastore_search_sql` against relevant financial packages, delivering a comparative table. ### Developing a real-time city metrics dashboard A developer needs to build an app that shows the current ratio of public services (Health vs. Education). They use their agent to first run `get_package` on both datasets, inspect the schema via `get_resource`, and then construct a unified query using `datastore_search_sql` for clean input. ### Academic research on public health trends A researcher needs to compare vaccination rates across different neighborhoods. They use `list_tags` to narrow down 'Health' data, then use `get_group` to focus only on relevant metrics packages, finally running targeted searches via `datastore_search` until they find the specific year-over-year comparison resource. ### Mapping city governance for a policy paper A consultant needs an overview of which secretariats handle what. They run `list_organizations` to get a master list, then use `get_organization` on the top five results to map out their specific mandates and data holdings before writing the policy whitepaper. ## Benefits - Stop manual downloading. You don't have to click through zip files or download CSVs just to find a column name. Your agent handles the connection and prepares the data for you right in your client's context. - Get cross-departmental views. Instead of checking the Health department site, then the Education site, run `list_organizations` first. This shows you all the relevant players contributing to city metrics. - Precision querying with SQL. When simple searches fail, use `datastore_search_sql`. You write a clean query—like 'SELECT * WHERE year > 2020'—and get structured results without knowing the underlying database schema. - Understand data lineage. Before trusting a dataset, run `get_package` and check its metadata. This confirms who owns it (`get_organization`), what themes it covers, and how fresh the source material is. - Speed up discovery. If you're hunting for anything related to 'transportation,' don't browse everything. Use `search_packages` or filter by tags to cut through the noise instantly. ## How It Works The bottom line is that you get raw, structured city data delivered to your agent's context without manual downloads or API endpoint management. 1. Subscribe to the São Paulo (Cidade) server. 2. (Optional) Provide your API Key for higher rate limits. 3. Tell your AI agent what data you need. The agent will automatically select and execute the necessary sequence of tools—like `list_organizations` followed by a query using `datastore_search_sql`. ## Frequently Asked Questions **How do I search São Paulo public data using datastore_search_sql?** You use the `datastore_search_sql` tool. You must first identify a specific resource (file) ID, then format your query exactly like standard SQL: SELECT column FROM table WHERE condition. **Which tool should I use to find all datasets related to 'Education'?** You should start with `list_groups` or `search_packages`. If you know the theme, using the group list helps focus your initial search before running a broad query. **I need details on what a dataset is called; which tool do I use?** Use the `get_package` tool. This gives you the metadata for an entire dataset, showing all its associated resources and tags before you try to query it. **How can I find out which department owns a specific dataset?** The `get_organization` tool lets you check department details. If you know the package ID, use that in conjunction with `get_package` to see the owning organization listed. **When I use `list_packages`, does it show every single data source in the São Paulo Open Data Portal?** Yes, running `list_packages` provides a complete inventory of published datasets. This function lists all available packages across the entire city portal, giving you a comprehensive view regardless of which department owns the data. **If my SQL query fails using `datastore_search_sql`, how can I diagnose the error?** The tool will return a specific database error code and message detailing the failure. If you get an error, check your column names against the resource's metadata to ensure they match the data schema. **How do I handle higher rate limits when searching many datasets with `search_packages`?** You must provide your personal São Paulo Open Data API Key in the request headers. Using a dedicated key raises your service ceiling, letting you run larger data discovery jobs without hitting throttling limits. **When I use `get_resource`, what specific details do I get about the file format?** You receive detailed metadata that specifies the resource's native format and structure. This confirms if it’s a CSV, JSON, or another type of structured data before you try to load or query it. **How can I search for datasets related to a specific topic like 'Health'?** You can use the `search_packages` tool with the query 'saúde'. The agent will return a list of matching datasets available in the portal. **Can I perform SQL queries on the data directly?** Yes! If a resource is stored in the DataStore, you can use the `datastore_search_sql` tool to run standard SQL queries against the resource ID. **How do I find which city departments have published data?** Use the `list_organizations` tool to see all registered entities. Then, use `get_organization` with a specific ID to see all datasets owned by that department.