# CARTO MCP Server The CARTO MCP Server enables AI agents to interact with your organization's geospatial data and tools through the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP). With it, agents can explore data warehouse connections, search for tables, run workflows, and visualize results on interactive maps. The server exposes two categories of tools: * **Built-in tools** for data exploration and map visualization, available to all accounts by default. * **Workflow tools** created by your team in CARTO Workflows, exposing organization-specific logic as MCP tools. This allows agents like Claude or ChatGPT answer spatial questions using your own data and processes. {% hint style="info" %} In the future CARTO will expand support by exposing core GIS operations (e.g., geocoding, isochrones, routing) directly as MCP Tools. Please get in touch if you're interested in this feature. {% endhint %} ## Using CARTO MCP Server 1. **Get the MCP Server URL** In your CARTO Workspace, go to **Developers > Workflow API & MCP Server**. Copy the MCP Server URL displayed under the CARTO AI section. The URL follows this pattern: ``` https://.api.carto.com/mcp/ ``` 2. **Connect to the MCP Server** Once you have the URL, connect using one of the following methods: * [**OAuth:**](https://docs.carto.com/carto-mcp-server/carto-mcp-server/connecting-with-oauth) for web-based platforms like Claude.ai that handle authentication natively. * [**API Access Tokens**](https://docs.carto.com/carto-mcp-server/carto-mcp-server/connecting-with-api-tokens)**:** for CLI-based agents like Gemini CLI. *** ## Available tools The CARTO MCP Server provides built-in tools for data management and visualization, plus any data preparation and analytical workflow your organization has published as [MCP Tools in CARTO Workflows](https://docs.carto.com/carto-user-manual/workflows/workflows-as-mcp-tools). Please check our [MCP Tools Reference](https://docs.carto.com/carto-mcp-server/carto-mcp-server/mcp-tools-reference) to access detailed information about the different tools available by default in our MCP Server. ### Workflows as MCP tools The CARTO MCP Server exposes any workflows your organization has published as MCP tools. For each type of spatial question you want an agent to answer, you design a workflow that defines the logic, inputs, and outputs. At a high level, the process is: 1. **Design a Workflow** that resolves a specific spatial problem. 2. **Expose the Workflow as an MCP Tool** by adding descriptions, inputs, and outputs that follow the MCP specification. 3. **Keep the Tool updated** by syncing the workflow whenever changes are made. For step-by-step guidance on building MCP Tools in Workflows, see the [**Workflows as MCP Tools**](https://docs.carto.com/carto-user-manual/workflows/workflows-as-mcp-tools) documentation. #### Best Practices To ensure reliable performance and accurate results when exposing Workflows as MCP Tools, consider the following guidelines: * **Keep tool descriptions clear and specific**: Write concise descriptions that explain what the tool does and when it should be used. This helps the agent choose the right tool. * **Define inputs precisely**: Use descriptive names and types for all parameters. Avoid ambiguous labels that could confuse the agent. * **Test workflows thoroughly**: Run workflows manually before exposing them to confirm that the outputs match expectations. * **Choose the right output mode**: Use Sync for lightweight, fast queries; use Async for long-running processes. {% hint style="info" %} Bear in mind that with **Async** mode, the agent will need to poll for the status of the execution and make an additional query to get results when the job is finalized. Implementing this logic in your agent's prompt might require additional work. {% endhint %} * **Version and update carefully**: When making changes to workflows, sync updates promptly and communicate changes to relevant users of the MCP Server. * **Monitor usage and errors**: Track how tools are used and review errors to refine workflows or adjust descriptions as needed. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.carto.com/carto-mcp-server/carto-mcp-server.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.