How to Use the WorkOS MCP in OpenAI Agents SDK

Q: How do I list all WorkOS organizations using OpenAI Agents SDK?

You call the listworkosorganizations tool. It returns a full list of every organization recorded in the WorkOS account, letting your agents know exactly what's available.

Q: How does WorkOS manage directory listings with OpenAI Agents SDK?

The MCP Server provides several tools, including listdirectories, which lists all active sync instances. You can then get specific details on users (listdirectoryusers) or groups using those same connections.

Q: What if I need to check SSO status with WorkOS and OpenAI Agents SDK?

You can run listssoconnections first. Then, use getssoconnectiondetails on a specific connection ID to confirm its current operational state.

Connect WorkOS to your OpenAI Agents SDK for production-grade enterprise management.

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 OpenAI Agents SDK

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Managing the MCP Server with OpenAI Agents SDK

The `list_workos_organizations` tool lets you see every organization in the account. This prevents agents from guessing which environment they should be working in. You can also use `create_workos_organization` to spin up a brand new record, providing both the name and a list of authorized domains.

Directory Sync Visibility

Want to know who's using what? The `list_directory_users` tool pulls every user synced from a directory. This is crucial for any agent needing to validate credentials. You can pair that with `list_directory_groups` to list all groups synchronized, giving your agents full visibility into organizational structure.

Auditing and SSO Checks

Agents need to know what's going down. Call `get_audit_log_events` to pull a stream of events that happened in the organization. This provides immediate context for any workflow failure. Plus, use `list_sso_connections` and `get_sso_connection_details` to check the current status of single sign-on setups.

Setup guide

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

Create your Agent

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

Run the agent

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

You call the `list_workos_organizations` tool. It returns a full list of every organization recorded in the WorkOS account, letting your agents know exactly what's available.

Yep. If you have a specific ID (like an Okta or Azure AD ID), `get_directory_details` pulls all the necessary metadata for that instance. This keeps your agents accurate.

The MCP Server provides several tools, including `list_directories`, which lists all active sync instances. You can then get specific details on users (`list_directory_users`) or groups using those same connections.

This MCP Server primarily touches organizational metadata, directory user lists, group memberships, and audit log event streams. It doesn't handle raw PII, just the structured records of who belongs where.

You can run `list_sso_connections` first. Then, use `get_sso_connection_details` on a specific connection ID to confirm its current operational state.

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