How to Use the Foursquare MCP in Pydantic AI

Q: What's the setup process for Pydantic AI and the Foursquare MCP server?

It's minimal. After pip install, you instantiate the MCPToolset with the server URL. Then you pass that toolset into your Agent's constructor. Pydantic AI handles the rest.

Get type-safe, validated Foursquare data in your Python agent with Pydantic AI. No more guessing API schemas.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Foursquare MCP to Pydantic AI

Create your Vinkius account to connect Foursquare 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 Foursquare with Pydantic AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Search for places with confidence

When your agent calls `search_places` or `autocomplete_venues`, Pydantic AI automatically parses the JSON response into a Pydantic model. You're not just hoping the data is correct. You know it is. If a field is missing, or the wrong type, or null when it shouldn't be, your code gets an immediate `ValidationError`. This stops silent bugs and corrupted data before they can break your agent's logic. You code against a predictable schema, and Pydantic AI enforces it.

Get details with runtime strictness

Using `get_place_details` or `get_place_photos` returns a fully-typed object, not a loose dictionary. This guarantees a photo URL from `get_place_photos` is always a string and a rating from `get_place_details` is always a number. No more defensive `if data is not None:` checks. This strictness works with any LLM you use with Pydantic AI — OpenAI, a local model, it doesn't matter. The data validation happens in your code, giving you a stable, reliable interface to this Foursquare MCP Server, regardless of the model or the backend.

Build geospatial functions that work

Define a search area with `search_within_polygon` and trust that the response is a clean list of valid place objects. Pydantic AI validates the data coming back from the API call, so your agent can focus on its task instead of data cleaning. This validation works on both sides of the MCP tool call. It ensures the data you send is correct, and the data you get back is correct. It's the most reliable way to build location-aware agents in Python.

Setup guide

Set up Foursquare 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": {
        "foursquare-mcp": {
            "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
        }
    }
})

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

result = await agent.run("List recent Foursquare 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 Foursquare. 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 Foursquare 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 Foursquare MCP in Pydantic AI

It validates the API response against a Pydantic model at runtime. If the JSON from a tool like `get_place_details` doesn't match the expected schema—for example, a missing field or wrong data type—Pydantic AI raises a `ValidationError` immediately. This prevents bad data from ever reaching your agent's logic.

Any of them. Pydantic AI is model-agnostic. You can use models from OpenAI, Anthropic, Google, or even run local models. The type-safety and data validation are features of the Pydantic AI framework itself, not the LLM.

There is a small, usually negligible, overhead for the runtime data validation. For most applications, the benefit of catching data errors early and preventing bugs far outweighs the microseconds spent on validation. It's a trade-off for correctness.

It's minimal. After `pip install`, you instantiate the `MCPToolset` with the server URL. Then you pass that toolset into your `Agent`'s constructor. Pydantic AI handles the rest.

Pydantic AI processes the data locally within your Python application's memory. When your agent calls a tool like `get_place_details`, the Foursquare data (address, phone number, etc.) is fetched by the Vinkius server and sent to your agent. Pydantic's validation happens on your machine, and the data doesn't persist unless your code explicitly saves it.

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