How to Use the WorkOS MCP in Pydantic AI

Q: How does WorkOS help manage organizations with Pydantic AI?

The agent uses tools like createworkosorganization or listworkosorganizations. Because the response is validated, you're guaranteed that the organization data returned matches your expected Python schema.

Q: Can I list directories and users with Pydantic AI?

Yes. Use listdirectories first to find all sync instances. Then, use listdirectoryusers or listdirectorygroups. The response structure is always validated against your models.

Q: How do I check audit logs using WorkOS and Pydantic AI?

You call getauditlogevents to pull the event stream. Since this data is typed, you can process every single log event confidently without needing extra checks for field existence.

Q: What happens if I use WorkOS and Pydantic AI on directory metadata?

If you call getdirectorydetails, the returned metadata is instantly validated. If the API gives you unexpected data, your agent fails immediately with a specific validation error—no silent corruption.

Connect WorkOS to your Pydantic AI for type-safe, validated production workflows.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect WorkOS MCP to Pydantic AI

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Working with the MCP Server in a Type-Safe Way

The `list_workos_organizations` tool gives you an exact list of organizations. Because Pydantic validates every response, your agent knows exactly what fields and types to expect for each record. When building production pipelines, this prevents silent failures caused by unexpected API output.

Validating Directory Sync Data

Need to check users? Use `list_directory_users`. If the underlying WorkOS data changes or returns an unknown field, Pydantic catches it. Your agent fails loudly instead of hallucinating fields. It works the same way when you list groups using `list_directory_groups`.

Retrieving Organizational Status

To get general org info, run `get_organization_details`. If the API returns a field that doesn't match your defined Pydantic model, the agent stops. This is key for reliable code. You can also check SSO status using `list_sso_connections` and validate the results with type checking.

Setup guide

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

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

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

The agent uses tools like `create_workos_organization` or `list_workos_organizations`. Because the response is validated, you're guaranteed that the organization data returned matches your expected Python schema.

Yes. Use `list_directories` first to find all sync instances. Then, use `list_directory_users` or `list_directory_groups`. The response structure is always validated against your models.

You call `get_audit_log_events` to pull the event stream. Since this data is typed, you can process every single log event confidently without needing extra checks for field existence.

The MCP Server handles organizational records, user lists, group memberships, SSO details, and audit log events. The primary data types are structured strings (names, IDs) and complex event objects.

If you call `get_directory_details`, the returned metadata is instantly validated. If the API gives you unexpected data, your agent fails immediately with a specific validation error—no silent corruption.

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