How to Use the R2R MCP in OpenAI Agents SDK

Q: How does R2R handle vector searches inside OpenAI Agents SDK?

The agent uses the search tool to execute vector queries against your R2R instance. It returns matching document chunks directly to the agent's context window.

Q: Can my OpenAI Agents SDK pipeline verify the R2R MCP Server health?

Yes. The agent calls the gethealth tool to check the status of your database cluster before running heavy search operations. This prevents agent timeouts during high-traffic periods.

Q: How do I load the R2R MCP Server in my OpenAI Agents SDK code?

Install the package with pip install openai-agents. Use the MCPServerStreamableHttp class with your endpoint URL, and pass it in the mcpservers list when instantiating your agent.

Q: How can an agent pull a specific file's details?

The agent invokes getdocument with the document ID. This returns the metadata and indexing status, allowing the agent to confirm if a file is ready for querying.

Give your OpenAI Agents SDK production pipelines direct access to R2R vector search and document management.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers — Included with Plan

Connect R2R MCP to OpenAI Agents SDK

Create your Vinkius account to connect R2R to OpenAI Agents SDK — we handle the hosting, security, and runtime updates so you don't have to. No server setup required.

GDPR Included with Plan

Setup R2R with OpenAI Agents SDK

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Run Semantic Queries directly in OpenAI Agents SDK

The `search` tool exposes vector retrieval directly to your Python agents. By executing a search, your agent scans your entire R2R knowledge base and extracts relevant document chunks without needing manual keyword matching. You configure this by passing the streamable HTTP server parameters to your `Agent` constructor. The agent automatically registers the tool, letting it query vector indexes on demand during run execution.

Execute Precise RAG Queries with Built-in Verification

The `rag_query` tool lets your agent execute retrieval-augmented generation directly inside its execution loop. It queries your documents, pulls context, and returns a synthesized answer based strictly on your ingested files. Because the OpenAI Agents SDK supports strict guardrails and validation, you can trace exactly which documents were accessed. If the agent attempts to fetch context from unauthorized collections, your guardrails catch it before execution.

Manage Document Collections and Verify Health

The `get_health` tool monitors your system state, while `list_documents` and `get_document` inspect document structures. This combination gives your production pipelines full visibility into which files are indexed. Grouping files is straightforward with `list_collections`. Your agent uses this information to restrict its queries to specific document groups, ensuring users only access files they are permitted to see.

Setup guide

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

Create your Agent

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

Run the agent

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

The agent uses the `search` tool to execute vector queries against your R2R instance. It returns matching document chunks directly to the agent's context window.

Yes. The agent calls the `get_health` tool to check the status of your database cluster before running heavy search operations. This prevents agent timeouts during high-traffic periods.

Install the package with `pip install openai-agents`. Use the `MCPServerStreamableHttp` class with your endpoint URL, and pass it in the `mcp_servers` list when instantiating your agent.

The agent invokes `get_document` with the document ID. This returns the metadata and indexing status, allowing the agent to confirm if a file is ready for querying.

Your raw document files and vector embeddings stay inside your private R2R instance. The server only transmits query strings and retrieved text snippets over an encrypted HTTP connection, meaning your files never sit on external servers.

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