HomeDocumentationLoginTry for free

CARTO MCP Server

MCP Tools let you expose Workflows as tools that AI Agents can use. This means you can build custom geospatial operations in Workflows and make them available to any MCP-compliant agent.

For example, you could create a Workflow that finds optimal delivery routes, then expose it as an MCP Tool. An agent like Gemini CLI could then call that tool automatically when someone asks a routing question.

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.

How it works:

  1. Build a Workflow that solves a specific problem

  2. Configure it as an MCP Tool (add descriptions, inputs, and outputs)

  3. Connect an agent to your CARTO MCP Server

  4. The agent can now use your custom tools

Step 1: Create a Workflow

Each MCP Tool needs a Workflow behind it. Design workflows that solve the specific questions you want agents to answer. For detailed instructions on building Workflows as MCP Tools, see the Workflows as MCP Tools documentation.

Step 2: Create an API Access Token

The MCP Server uses API tokens for authentication.

  1. In the CARTO Workspace, navigate to Developers > Credentials and create a new API Access Token

  2. Under Allowed APIs, select the MCP Server permission

  3. Copy the token and save it securely

You'll need this token to connect agents to your MCP Server.

Step 3: Connect an Agent

Once your workflow and token are ready, connect your agent to the CARTO MCP Server. Here's an example using 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

Best Practices

Write clear tool descriptions Explain what the tool does and when to use it. This helps agents choose the right tool for each question.

Define inputs precisely Use descriptive parameter names and types. Vague labels confuse agents.

Test workflows first Run workflows manually before exposing them as tools. Verify the outputs match what you expect.

Choose the right output mode Use Sync for quick queries. Use Async for long-running operations. Keep in mind that Async requires the agent to poll for status and fetch results when complete, which may need additional prompt engineering.

Keep tools updated When you modify a workflow, sync it promptly. Let users know if tool behavior changes.

Monitor usage Review how tools are used and check for errors. Use this to refine workflows or improve descriptions.

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.

Last updated

Was this helpful?