Connect Sanity Context with OpenAI Agents SDK

Connect Sanity Context to a Python agent using the OpenAI Agents SDK with built-in MCP support.

This example connects Sanity Context to a Python agent using the OpenAI Agents SDK. The SDK has built-in MCP support and discovers tools automatically.

You need a Sanity Context MCP endpoint. If you haven't set one up yet, start with Sanity Context. You'll need:

• MCP endpoint URL: Shown in the Sanity Context document in Studio.
• Sanity API read token: Create one at sanity.io/manage.
• OpenAI API key: The SDK reads it from OPENAI_API_KEY.
• Python 3.10 or later: Required by openai-agents.

pip install openai-agents httpx python-dotenv

Create a .env file next to agent.py. load_dotenv() reads it. Replace each placeholder with your own value:

SANITY_CONTEXT_MCP_URL=YOUR_MCP_ENDPOINT_URL
SANITY_API_READ_TOKEN=YOUR_SANITY_READ_TOKEN
OPENAI_API_KEY=YOUR_OPENAI_API_KEY

Connect to the MCP endpoint, fetch initial context, and run the agent:

import asyncio
import os
from urllib.parse import urlparse, urlunparse

import httpx
from dotenv import load_dotenv
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp, create_static_tool_filter

load_dotenv()

MCP_URL = os.environ["SANITY_CONTEXT_MCP_URL"]
API_TOKEN = os.environ["SANITY_API_READ_TOKEN"]


async def main():
    # 1. Fetch initial context via HTTP
    parsed = urlparse(MCP_URL)
    initial_context_url = urlunparse(
        parsed._replace(path=parsed.path.rstrip("/") + "/initial-context")
    )

    async with httpx.AsyncClient() as http:
        resp = await http.get(
            initial_context_url,
            headers={"Authorization": f"Bearer {API_TOKEN}"},
        )
        resp.raise_for_status()
        initial_context = resp.text

    # 2. Connect to Sanity Context MCP
    async with MCPServerStreamableHttp(
        name="sanity",
        params={
            "url": MCP_URL,
            "headers": {"Authorization": f"Bearer {API_TOKEN}"},
        },
        # The default is 5 seconds, which is tight for a large schema
        client_session_timeout_seconds=30,
        tool_filter=create_static_tool_filter(
            blocked_tool_names=["initial_context"],
        ),
    ) as server:
        # 3. Create the agent and run it
        agent = Agent(
            name="Assistant",
            instructions=(
                "You are a helpful assistant.\n\n"
                "# Data reference\n\n"
                "Use this to understand what's available and write better queries.\n\n"
                + initial_context
            ),
            mcp_servers=[server],
        )

        result = await Runner.run(agent, "What content do we have?")
        print(result.final_output)


asyncio.run(main())

Every Sanity Context integration follows three steps:

• Fetch initial context via the /initial-context HTTP endpoint and inject it into your system prompt. This gives the agent a compressed schema overview so it can write accurate queries from the start — and saves a tool call on every conversation.
• Connect to MCP using MCPServerStreamableHttp. The SDK discovers tools automatically when you pass mcp_servers to the agent. Use create_static_tool_filter to block the initial_context tool since you've already fetched it.
• Create the agent and run it with Runner.run. The agent will make tool calls as it explores your content. Without a model argument, Agent uses the SDK's default model, and credentials come from OPENAI_API_KEY, so a missing key fails at this step, after the MCP connection has already succeeded.

Three failures account for most first runs:

• KeyError: 'SANITY_CONTEXT_MCP_URL': The .env file is missing, or isn't in the directory you run the script from. load_dotenv() returns without error when it finds no file.
• httpx.HTTPStatusError: Client error '401 Unauthorized' raised by resp.raise_for_status(): The value in SANITY_API_READ_TOKEN isn't a valid Sanity API read token.
• openai.OpenAIError: Missing credentials. Please pass an `api_key`, `workload_identity`, `admin_api_key`, or set the `OPENAI_API_KEY` or `OPENAI_ADMIN_KEY` environment variable.: This surfaces at Runner.run, after the MCP connection and the initial-context fetch have already succeeded.

• Sanity Context patterns and best practices: Production patterns for public assistants, personalized agents, and multi-backend setups.
• Add insights to Sanity Context: Track and analyze agent conversations.
• AI shopping assistant walkthrough: A full reference implementation using Next.js and the Vercel AI SDK.