How to Use the Geocodio MCP in OpenAI Agents SDK

Q: How does the Geocodio MCP server work with the OpenAI Agents SDK?

You pass the server's URL to the MCPServerStreamableHttp class in your Python code. The OpenAI Agents SDK then automatically discovers all the Geocodio tools, like geocodeusaddress, making them available for your agent to call.

Q: What's the best way to handle batch geocoding with Geocodio and the OpenAI Agents SDK?

For bulk jobs, have your agent call the batchgeocodeaddresses tool. This is way more efficient than looping through single lookups. The SDK handles the async call, so your agent can process a large list of addresses in one shot.

Geocode addresses and map US/Canada legislative districts using your OpenAI Agents SDK.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Geocodio MCP to OpenAI Agents SDK

Create your Vinkius account to connect Geocodio to OpenAI Agents SDK 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 Geocodio with OpenAI Agents SDK

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Batch Geocode with Agent Guardrails

Your agent can feed hundreds of addresses into `batch_geocode_addresses` and get back clean coordinates. The SDK's guardrails mean you can define pre-execution checks, making sure your agent doesn't try to geocode malformed data or run up your bill. It's about letting the agent work without constant supervision. You can also chain agents. One agent cleans addresses, then hands off to a specialized geocoding agent using `geocode_us_address` for single lookups or the batch tool for bulk jobs. The whole sequence is tracked in your OpenAI dashboard, so you have a full audit trail.

Pull Census Data into Your Agent

This isn't just about lat/long. Have your agent use `geocode_enriched_fields` to pull specific census tract or congressional district data for an address. It's a direct way to enrich your application's data without hitting a separate API. Because the OpenAI Agents SDK automatically discovers tools from this MCP server, you don't write any integration code. Your agent just knows `reverse_enriched_fields` exists and can use it to find, say, school district information for a given coordinate.

Production-Ready MCP Server Integration

This server is managed. You get one endpoint and a token, and that's it. Your agent connects and the tools are available. No need to worry about hosting or scaling the geocoding service yourself. Set `cacheToolsList=True` in the SDK setup. Your agent won't have to fetch the tool list on every startup, which is exactly what you want for a production system where initialization speed matters. This makes your agent deployments faster and more reliable.

Setup guide

Set up Geocodio 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 Geocodio tools at runtime.
3

Create your Agent

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

Run the agent

Call Runner.run(agent, prompt) to execute. The agent invokes the appropriate Geocodio 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="Geocodio Agent",
            instructions="You have access to Geocodio 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 Geocodio. 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 Geocodio 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 Geocodio MCP in OpenAI Agents SDK

You pass the server's URL to the `MCPServerStreamableHttp` class in your Python code. The OpenAI Agents SDK then automatically discovers all the Geocodio tools, like `geocode_us_address`, making them available for your agent to call.

The SDK discovers all available tools automatically. To restrict access, you'd implement logic within your agent's control loop or use the SDK's built-in guardrails to prevent calls to specific tools you want to block.

For bulk jobs, have your agent call the `batch_geocode_addresses` tool. This is way more efficient than looping through single lookups. The SDK handles the async call, so your agent can process a large list of addresses in one shot.

Yes. You can create a dedicated geocoding agent and pass it the Geocodio server. Other agents can then hand off tasks, like a list of addresses, to your specialist agent for processing.

Your agent sends address strings to the Vinkius-hosted server, which then proxies the request to Geocodio. All traffic is over HTTPS, and the ephemeral server environment on Vinkius doesn't persist your data beyond the request's lifecycle.

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