How to Use the CountryStateCity MCP in OpenAI Agents SDK

Q: Can CountryStateCity help OpenAI Agents SDK handle regional handoffs?

Yes, by combining tools like liststates and getstate to split routing tasks among specialized agents. One agent identifies the state, while another handles local city queries. This separation of duties keeps your token usage low and your system reliable.

Q: Does the CountryStateCity MCP Server support caching in OpenAI Agents SDK?

Setting cacheToolsList=True in your agent configuration prevents the SDK from repeatedly querying the server schema. This speed boost is crucial when your agent uses listcountries frequently during heavy address validation runs.

Q: What happens if a user queries a city in a non-existent state?

Your agent runs listcitiesbystate and returns an empty list or error. OpenAI's built-in guardrails allow you to catch this result and instruct the agent to prompt the user for a correction instead of hallucinating a fake city.

Query global geography with safety-first OpenAI Agents SDK pipelines using this dedicated MCP Server.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect CountryStateCity MCP to OpenAI Agents SDK

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Validate ISO Codes with OpenAI Agents SDK

`get_country` fetches exact ISO 3166-1 alpha-2 codes and metadata directly into your OpenAI agent's context. Your production agent checks incoming geographic data against this single source of truth before triggering downstream workflows. You configure this MCP Server by passing the server to your `Agent` constructor via `mcp_servers=[server]` using `MCPServerStreamableHttp`. Enabling `cacheToolsList=True` keeps your agent fast and prevents redundant network hops during high-traffic validation runs.

Route Queries Using State and City Tooling

`list_states` and `list_cities_by_state` work together to let your agent hand off complex routing tasks to specialized sub-agents. A regional specialist agent handles the state lookup, then hands the context over to a city-level delivery agent. Built-in guardrails in the OpenAI Agents SDK intercept these tool calls to ensure your agent doesn't hallucinate non-existent regions. If a state doesn't exist in the data, the agent stops the pipeline immediately, protecting your production database from bad inputs.

Global Address Standardization via MCP

`list_countries` and `get_state` give your agent the reference data needed to fix messy user-entered addresses. The agent takes raw text, checks it against the geography database, and outputs clean, standardized records. Tracking these operations is simple because every tool execution shows up in your OpenAI dashboard. You monitor exactly how much context your agent uses when cleaning geographic records, making debugging straightforward and fast.

Setup guide

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

Create your Agent

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

Run the agent

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

Install the library with pip, then initialize the server with `MCPServerStreamableHttp` using your Vinkius endpoint. Pass this instance in the `mcp_servers` list when instantiating your `Agent`. Your agent discovers the geography tools instantly.

Yes, by combining tools like `list_states` and `get_state` to split routing tasks among specialized agents. One agent identifies the state, while another handles local city queries. This separation of duties keeps your token usage low and your system reliable.

Setting `cacheToolsList=True` in your agent configuration prevents the SDK from repeatedly querying the server schema. This speed boost is crucial when your agent uses `list_countries` frequently during heavy address validation runs.

Your agent runs `list_cities_by_state` and returns an empty list or error. OpenAI's built-in guardrails allow you to catch this result and instruct the agent to prompt the user for a correction instead of hallucinating a fake city.

Your geographic queries and ISO lookups run inside a secure V8 isolate sandbox on Vinkius. We never store the country, state, or city names your agents process. All transit is encrypted, ensuring your users' location queries remain 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