How to Use the Pelias Geocoder MCP in OpenAI Agents SDK

Q: Can my agent switch between different search layers like venues or addresses?

Yes, your agent can invoke searchlayerfilter to target specific GIS datasets. This lets the model ignore street addresses when it only needs to find administrative regions or specific points of interest.

Build production-grade agents with OpenAI Agents SDK that resolve addresses and coordinates using the Pelias Geocoder.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers — Included with Plan

Connect Pelias Geocoder MCP to OpenAI Agents SDK

Create your Vinkius account to connect Pelias Geocoder to OpenAI Agents SDK — we handle the hosting, security, and runtime updates so you don't have to. No server setup required.

GDPR Included with Plan

Setup Pelias Geocoder with OpenAI Agents SDK

Ask AI about this MCP

ChatGPT

Claude

Perplexity Vinkius runs on Gemini

Gemini

Grok

Run clean spatial lookups inside OpenAI Agents SDK.

Your OpenAI agents can pinpoint exact locations on a map using the Pelias engine without messy manual API integrations. By using `search_geocode` and `reverse_geocode` through this MCP Server, the agent parses raw user strings or GPS coordinates into structured location data during active runs. This setup lets your agent make decisions based on real physical locations. If a user asks for nearby services, the agent calls `reverse_distance_limit` to search within a tight radius, keeping the spatial context clean and highly accurate.

Validate address inputs via this MCP Server.

Stop letting your agents guess where an address is. This MCP Server gives your OpenAI Agents SDK the ability to run autocomplete queries as users type or when processing messy data streams. Using `search_autocomplete` and `structured_geocoding` directly in your agent loop prevents hallucinated addresses. The agent verifies the location against the Pelias index before committing the data to your database, saving you from failed deliveries or broken logistics.

Filter spatial queries with native constraints.

Restrict your agent's focus so it doesn't return coordinates from the wrong side of the globe. With `search_country_filter` and `search_bounding_box`, your agent restricts its search area to specific geographic boundaries or ISO country codes. This prevents your OpenAI agent from routing a delivery to London, Ontario when the user meant London, UK. It uses `search_focus_bias` to prioritize points near the user's current coordinate trace, keeping queries fast and highly relevant.

Setup guide

Set up Pelias Geocoder MCP in OpenAI Agents SDK

Prerequisites

Python 3.10+ installed
openai-agents package (pip install openai-agents)
Active Vinkius subscription with a valid endpoint token

1

Install the SDK

Run pip install openai-agents to install the OpenAI Agents SDK. The MCP integration is built-in — no extra dependencies needed.
2

Connect via SSE transport

Use MCPServerSse with your Vinkius endpoint URL. Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com. The SDK auto-discovers all Pelias Geocoder tools at runtime.
3

Create your Agent

Pass the MCP to Agent(mcp_servers=[server]). The agent receives Pelias Geocoder tools as native definitions — JSON schemas resolve automatically.
4

Run the agent

Call Runner.run(agent, prompt) to execute. The agent invokes the appropriate Pelias Geocoder tools and returns structured results. Copy the full example on the right to get started.

agent.py

import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerSse

async def main():
    async with MCPServerSse(
        url="https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
    ) as server:
        agent = Agent(
            name="Pelias Geocoder Agent",
            instructions="You have access to Pelias Geocoder tools.",
            mcp_servers=[server],
        )
        result = await Runner.run(agent, "List recent transactions")
        print(result.final_output)

asyncio.run(main())

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 Pelias Geocoder. 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 Pelias Geocoder 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 Pelias Geocoder MCP in OpenAI Agents SDK

You initialize the server using the streamable HTTP constructor with your Vinkius endpoint. Then, pass that server instance directly into the mcp_servers list when instantiating your Agent object. The SDK automatically discovers all ten tools like search_geocode with zero manual configuration.

Yes, every tool invocation is fully tracked. When your agent calls reverse_geocode or lookup_place_id, the inputs, outputs, and execution times appear directly in your OpenAI developer dashboard. This makes debugging coordinate mismatches or latency issues straightforward.

You write validation checks that run before the agent executes tools like reverse_distance_limit. If the agent tries to search a radius that is too wide, your guardrails catch the parameter violation and force the agent to correct its input before hitting the Pelias API.

Yes, your agent can invoke search_layer_filter to target specific GIS datasets. This lets the model ignore street addresses when it only needs to find administrative regions or specific points of interest.

Absolutely. Your coordinate pairs and address strings are processed in an ephemeral Vinkius sandbox that wipes memory after execution. No location history is saved on the server, keeping your users' physical movements completely private.

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