How to Use the IQAir MCP in Pydantic AI

Q: How can I verify that the weather API is online before querying?

Call the checkapistatus tool. This returns a simple status payload that your agent can check to avoid unnecessary polling when the service is down.

Run type-safe air quality and weather queries in Pydantic AI with strict runtime schema validation.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect IQAir MCP to Pydantic AI

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Safe localized weather and pollution lookups

The `get_nearest_city_air_quality` tool fetches real-time weather and pollution metrics for the city closest to the user's IP. Pydantic AI immediately validates this incoming JSON payload against your defined schemas, catching any unexpected field changes before they reach your application logic. This strict validation prevents silent failures in your production pipelines. If the external API changes its response structure, your agent halts immediately with a clear validation trace rather than propagating corrupted coordinates or air quality index data.

Validate global geography with the IQAir MCP Server

The `list_supported_countries` tool returns a clean list of all countries currently monitored by the station network. Your agent feeds this list into `list_supported_states` and `list_supported_cities` to build a type-safe location registry. This structure guarantees that your agent only requests air quality data for known, valid regions. Pydantic AI enforces type correctness on these returned lists, ensuring that every state and city name matches your expected string constraints.

Exact city monitoring with status validation

The `get_city_air_quality` tool retrieves specific pollution levels and weather conditions for a chosen city. Your agent can first verify the external service is online by calling `check_api_status` to ensure your data pipeline won't hang on a dead endpoint. This sequence keeps your automated reporting systems highly reliable. By running these tools through the unified MCP Server toolset interface, you ensure all environmental data is fully typed, structured, and ready for downstream processing.

Setup guide

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

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

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

Use the unified MCP Server toolset class to initialize the connection to your external Vinkius endpoint. Pass this toolset directly into your Agent constructor to expose the air quality tools.

The framework validates the incoming JSON against strongly-typed schemas at runtime. If a tool returns a coordinate or index that violates your model definitions, the agent raises a validation error immediately.

Yes. The MCP Server supports async HTTP and SSE transports, allowing your agent to query multiple cities concurrently without blocking your main event loop.

Call the `check_api_status` tool. This returns a simple status payload that your agent can check to avoid unnecessary polling when the service is down.

This server accesses IP addresses, geographic coordinates, and local pollution metrics. Vinkius runs the MCP Server in an isolated, ephemeral V8 sandbox, guaranteeing that your location data is processed securely and never persisted on disk.

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