How to Use the Convai MCP in Pydantic AI

Q: How do I connect the Convai MCP Server to Pydantic AI?

Install pydantic-ai-slimmcp and initialize MCPToolset with your Vinkius HTTP endpoint. Pass the toolset into your Agent constructor's toolsets argument to register the tools.

Q: Can I validate character backstories generated by Convai in Pydantic AI?

Yes. You can run generatebackstory and pipe the resulting text directly into a Pydantic model for validation. This lets you enforce content standards, length limits, and formatting rules before updating your character.

Q: How is my conversational transcript data secured?

All conversational transcript data processed via getchatsessiondetails is handled within Vinkius's ephemeral V8 sandboxes. Your game data is never stored locally or cached, maintaining strict player privacy.

Run type-safe character management pipelines with Convai and Pydantic AI to guarantee runtime data integrity.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Convai MCP to Pydantic AI

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Type-Safe Character Creation with Pydantic AI

The Convai MCP Server integrates with Pydantic AI to ensure that every character profile you build matches your exact schema. When your agent runs `create_character` or `update_character`, the incoming data is strictly validated against Pydantic models. If the Convai API returns an unexpected field or missing attribute, your pipeline fails loudly at runtime. This prevents corrupted character profiles from breaking your game client or saving bad data to your database.

Validate Narrative Triggers and Sections

This MCP Server lets you manage complex game states without worrying about silent schema changes. Your agent can execute `list_narrative_sections` and `create_narrative_trigger` while Pydantic AI validates the structure of the returned narrative trees. By enforcing strict type definitions, you can confidently let your agent write and edit game scripts. You get the flexibility of LLM-generated content with the safety of compile-time and runtime type checks.

Parse Conversation Evaluations Securely

The integration provides validation for analytical tools like `evaluate_conversation` and `get_chat_session_details`. When your agent pulls transcripts to grade player interactions, Pydantic AI parses the raw JSON into structured Python objects. This ensures your analytics engine never chokes on malformed transcript data. You can build reliable leaderboards, progression trackers, and grading systems that rely on clean, validated metrics.

Setup guide

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

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

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

Install `pydantic-ai-slim[mcp]` and initialize `MCPToolset` with your Vinkius HTTP endpoint. Pass the toolset into your `Agent` constructor's `toolsets` argument to register the tools.

Your agent will raise a validation error immediately. This MCP Server failure prevents silent data corruption, ensuring your application only processes perfectly structured character details and narrative triggers.

Yes. You can run `generate_backstory` and pipe the resulting text directly into a Pydantic model for validation. This lets you enforce content standards, length limits, and formatting rules before updating your character.

Yes, Pydantic AI natively supports async operations. Tools like `get_response` and `connect_live` run asynchronously, preventing blocking issues during real-time game loops or high-traffic chat sessions.

All conversational transcript data processed via `get_chat_session_details` is handled within Vinkius's ephemeral V8 sandboxes. Your game data is never stored locally or cached, maintaining strict player privacy.

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