CARTO MCP Server

The CARTO MCP Server enables AI Agents to use geospatial tools built with Workflows. By exposing workflows as MCP Tools, GIS teams can empower agents to answer spatial questions with organization-specific logic. Each tool follows the MCP specification, including a description, input parameters, and output, making them accessible to any MCP-compliant agentic application.

This approach allows organizations to:

• Build custom tools in Workflows that reflect their own data and processes.

• Securely expose those tools through an MCP Server.

• Integrate with agents such as Gemini CLI, enabling them to resolve spatial problems automatically.

Using CARTO MCP Server

Create a Workflow

MCP Tools in CARTO are powered by Workflows. For each type of question you want your AI Agent to answer, you will need to design one or more workflows. These workflows define the logic, inputs, and outputs that the agent can use.

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 documentation.

Create an API Access Token

The MCP Server requires authentication via an API Access Token:

1. In CARTO Workspace, create a new token.

2. In Allowed APIs, select the MCP Server permission scope.

3. Copy the token securely, as it will be required to connect the agent to the server.

Add MCP Server to your AI Agents

Once the workflow and token are ready, you can add the CARTO MCP Server to your agent. For example, with Gemini CLI:

gemini mcp add carto-pm-org \
  https://gcp-us-east1.api.carto.com/mcp/<account_id> \
  -H 'Authorization: Bearer <YOUR_API_TOKEN>' \
  -t http

• -t http specifies the transport protocol.

• The Authorization header includes the API Access Token created in the previous step.

After this setup, the agent will be able to call the MCP Tools you created with Workflows and return geospatial results in response to questions.

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.

• 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.