How to Use the CARTO MCP in Pydantic AI

Q: How do I hook up CARTO to Pydantic AI?

Install pydantic-ai-slimmcp and define an MCP connection pointing to your Vinkius HTTP endpoint. You pass this toolset into your Agent constructor. The framework handles the Streamable HTTP transport automatically.

Q: How does Pydantic AI handle CARTO async job polling?

Your agent calls pollasyncjobstatus every few seconds to check the state of pending queries. It parses the createdat and updatedat fields into strict datetime objects. If the job fails, the agent reads the exact error string to determine the next step.

Q: Can Pydantic AI agents import external files into CARTO?

Yes, triggering importexternalfile with a valid URL starts the ingestion process for zipped Shapefiles or GeoJSONs. The agent polls getimportstatus until it confirms the new table name exists in the warehouse. Validation ensures the URL format is correct before the request even fires.

Q: What happens if a CARTO dataset query returns unexpected fields?

When listmapdatasets pulls your organization's visualization metadata, Pydantic immediately validates the privacy settings and row counts. Any missing or malformed fields trigger a hard stop. Your agent will never operate on hallucinated dataset information.

Enforce strict schema validation on every CARTO spatial query and routing request using Pydantic AI.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect CARTO MCP to Pydantic AI

Create your Vinkius account to connect CARTO to Pydantic AI and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup CARTO with Pydantic AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Type-safe spatial querying

Executing `execute_sql_query` pulls JSON rows from your data warehouse directly into strict Pydantic models. If the database returns a missing geometry column, your agent fails loudly with a validation error instead of hallucinating the missing data. You catch schema drift the exact millisecond it happens. Long-running transformations rely on `create_async_sql_job` to push heavy ETL work to the warehouse backend. The agent tracks execution states via `poll_async_job_status` and validates the final output payload. This MCP Server ensures your spatial pipelines never swallow silent errors.

Reliable location data services

Running `geocode_batch_addresses` forces the agent to validate every single match quality indicator across the entire array. Bad matches trigger immediate pipeline rejections rather than corrupting your downstream CRM tables. You guarantee perfect coordinate integrity before any data hits your map. Single string resolutions use `geocode_address` to pull exact latitudes and longitudes. Pydantic AI checks the formatted address string against your expected schema format. The operation consumes LDS credits predictably while maintaining absolute data correctness.

Precision logistics with CARTO MCP Server

Invoking `calculate_isoline` generates a GeoJSON polygon representing your exact travel-time boundaries in seconds. The agent verifies the polygon coordinates against your geographic bounding boxes before approving the catchment zone. You prevent rogue agents from plotting service areas in the middle of the ocean. Point-to-point driving logistics run through `calculate_route` to extract exact distances in meters. Your framework validates the route geometry against standard GeoJSON specifications before passing it to the visualization layer. Every Vinkius execution returns mathematically provable results.

Setup guide

Set up CARTO MCP in Pydantic AI

Prerequisites

Python 3.10+ installed
pydantic-ai-slim[fastmcp] package
Active Vinkius subscription with a valid endpoint token

1

Install Pydantic AI with FastMCP
Run pip install "pydantic-ai-slim[fastmcp]". The FastMCP toolset replaces the deprecated MCPServerHTTP class with full protocol support.
2

Configure the FastMCPToolset
Pass a JSON-style config dict to FastMCPToolset with your Vinkius URL. Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com. Supports Streamable HTTP, SSE, and Stdio transports.
3

Create and run your agent
Pass the toolset to Agent(toolsets=[toolset]) and call agent.run(). Swap openai:gpt-4o for any supported model — Anthropic, Google, Mistral, or Groq.

agent.py

from pydantic_ai import Agent
from pydantic_ai.toolsets.fastmcp import FastMCPToolset

toolset = FastMCPToolset({
    "mcpServers": {
        "carto-mcp": {
            "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
        }
    }
})

agent = Agent(
    "openai:gpt-4o",
    toolsets=[toolset],
    system_prompt="You have access to CARTO tools.",
)

result = await agent.run("List recent CARTO transactions")
print(result.output)

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by CARTO. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect CARTO now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about CARTO MCP in Pydantic AI

Install pydantic-ai-slim[mcp] and define an MCP connection pointing to your Vinkius HTTP endpoint. You pass this toolset into your Agent constructor. The framework handles the Streamable HTTP transport automatically.

Your agent calls poll_async_job_status every few seconds to check the state of pending queries. It parses the created_at and updated_at fields into strict datetime objects. If the job fails, the agent reads the exact error string to determine the next step.

Yes, triggering import_external_file with a valid URL starts the ingestion process for zipped Shapefiles or GeoJSONs. The agent polls get_import_status until it confirms the new table name exists in the warehouse. Validation ensures the URL format is correct before the request even fires.

When list_map_datasets pulls your organization's visualization metadata, Pydantic immediately validates the privacy settings and row counts. Any missing or malformed fields trigger a hard stop. Your agent will never operate on hallucinated dataset information.

Your raw customer CRM lists and proprietary geocoding arrays run through a zero-trust V8 Isolate Sandbox hosted on Vinkius. The server processes the batch request and destroys the ephemeral environment immediately after returning the coordinates. Your Pydantic models only ingest the final validated outputs.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript