How to Use the Convex MCP in OpenAI Agents SDK

Q: How does the OpenAI Agents SDK handle Convex schema validation?

The SDK intercepts calls to runmutation and checks the payload against your target schema. If the agent generates bad arguments, the validation guardrails block the call before it reaches Convex.

Q: How does the Convex MCP Server protect my database payloads?

All data payloads sent via runquery or runmutation pass through an ephemeral, zero-trust V8 isolate. Vinkius never stores your database records or mutation arguments, keeping your production data strictly between your OpenAI Agents SDK and Convex.

Run Convex mutations and queries inside production OpenAI Agents SDK pipelines with built-in guardrails.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Convex MCP to OpenAI Agents SDK

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Query Convex via the OpenAI Agents SDK

The `run_query` tool fetches live data directly from your Convex database into your OpenAI Agents SDK runtime via this MCP tool. Your agent reads database state instantly to make decisions instead of relying on stale context or manual API calls. Because this tool runs inside the OpenAI SDK context, you can trace every database pull on your OpenAI developer dashboard. This setup ensures your production agent never hallucinates database records.

Write State with Convex Mutations

The `run_mutation` tool changes your backend state directly from the OpenAI Agents SDK agent. When your agent decides to update a user record, it triggers this mutation to write clean, validated data back to Convex. You get automatic guardrails before execution. The SDK validates the agent's proposed arguments against your Convex schema, stopping bad writes before they hit your production database.

Trigger Heavy Workloads with Actions

The `run_action` tool executes long-running side effects outside the database transaction using Convex actions. If your OpenAI Agents SDK agent needs to hit third-party APIs or process files, this tool offloads the heavy lifting. You can also use `run_function` to call specific Convex endpoints by their exact URL path. This keeps your agent's capabilities narrow while giving it targeted access to your entire backend through this MCP Server.

Setup guide

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

Create your Agent

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

Run the agent

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

You pass your Vinkius HTTP endpoint token when initializing the `MCPServerStreamableHttp` client. This single token handles all authentication, letting your OpenAI Agents SDK safely run queries and mutations without managing separate Convex keys.

Yes, you control this by configuring the agent's tool definitions during initialization. By limiting the tools passed to the agent constructor, you prevent the agent from calling unauthorized mutations or actions.

The SDK intercepts calls to `run_mutation` and checks the payload against your target schema. If the agent generates bad arguments, the validation guardrails block the call before it reaches Convex.

Running operations through this MCP Server adds minimal latency because Vinkius hosts the server on a fast V8 sandbox. Enabling `cacheToolsList=True` in your Python setup ensures the OpenAI Agents SDK doesn't waste time fetching tool schemas repeatedly.

All data payloads sent via `run_query` or `run_mutation` pass through an ephemeral, zero-trust V8 isolate. Vinkius never stores your database records or mutation arguments, keeping your production data strictly between your OpenAI Agents SDK and Convex.

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