How to Use the Box MCP in Pydantic AI

Q: How do I set up the Box server in Pydantic AI?

Initialize the MCPToolset with your Vinkius HTTP URL. Then pass this toolset directly into the toolsets argument of your Pydantic AI Agent, which registers the MCP toolsets.

Q: Does Pydantic AI validate the output of Box search queries?

Yes, every response from the searchcontent tool is validated against the MCP schema. Any missing or malformed fields in the search results trigger a clear runtime validation error.

Q: What happens if a search query returns no results?

The searchcontent tool returns an empty list, which safely conforms to the expected array schema. Your agent can handle this cleanly without throwing a validation exception.

Run type-safe Box file operations inside Pydantic AI with strict runtime validation for every tool response.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Box MCP to Pydantic AI

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

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Type-safe Box file querying with Pydantic AI

The `get_file_info` and `get_folder_info` tools fetch structured metadata that Pydantic AI validates against strict schemas at runtime. If the API returns unexpected fields, the framework raises a validation error immediately instead of letting corrupt data break your application. This prevents silent failures when your agent parses file sizes, modification dates, or folder IDs. You get predictable execution whether you use OpenAI, Anthropic, or local models.

Validate directory creation and structure

The `create_folder` and `list_folder_items` tools allow your agent to build and inspect directory trees in your Box account. Since everything goes through the MCP Server, the inputs and outputs are strictly typed. Your agent can safely navigate from the root folder "0" down to nested projects. If the model attempts to pass an invalid folder ID, the validation layer catches it before any bad API requests are sent.

Strict search and user auditing

The `search_content` and `list_users` tools return structured lists of files, folders, and enterprise members. Your agent can run deep content searches for PDFs or spreadsheets and receive guaranteed data formats. This makes writing downstream logic simple because you can trust the structure of the returned user lists using a dedicated MCP Server pipeline. You can map the output directly to custom Pydantic models for reporting or compliance checks.

Setup guide

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

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

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

Initialize the `MCPToolset` with your Vinkius HTTP URL. Then pass this toolset directly into the `toolsets` argument of your Pydantic AI Agent, which registers the MCP toolsets.

Yes, every response from the `search_content` tool is validated against the MCP schema. Any missing or malformed fields in the search results trigger a clear runtime validation error.

Yes, this setup is completely model-agnostic. You can use local LLMs or proprietary models, and Pydantic AI will still enforce strict schema validation on all Box tools.

The `search_content` tool returns an empty list, which safely conforms to the expected array schema. Your agent can handle this cleanly without throwing a validation exception.

Vinkius uses ephemeral V8 sandboxing to ensure your folder structures and user permissions are never stored on disk. Data is routed directly to your local runtime, keeping your enterprise directory layout completely confidential.

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