Connect Sanity Context with OpenAI Agents SDK

npm install @openai/agents zod

pnpm add @openai/agents zod

yarn add @openai/agents zod

bun add @openai/agents zod

zod is a required peer dependency of @openai/agents. If you type-check with tsc, set "skipLibCheck": true in tsconfig.json, because the SDK's own type files fail library checks. Set the module type in package.json so Node.js loads agent.ts as an ES module:

npm pkg set type=module

python3 -m venv .venv
source .venv/bin/activate
pip install openai-agents httpx python-dotenv

Install into a virtual environment. On recent Debian, Ubuntu and Homebrew Python installs, pip install against the system Python fails with externally-managed-environment.

import {Agent, MCPServerStreamableHttp, createMCPToolStaticFilter, run} from '@openai/agents'

const MCP_URL = process.env.SANITY_CONTEXT_MCP_URL
const API_TOKEN = process.env.SANITY_ORGANIZATION_TOKEN
if (!MCP_URL || !API_TOKEN) {
  throw new Error('Set SANITY_CONTEXT_MCP_URL and SANITY_ORGANIZATION_TOKEN')
}
const headers = {Authorization: `Bearer ${API_TOKEN}`}

// 1. Fetch the initial context (schema overview or Knowledge Base outline).
async function fetchInitialContext(): Promise<string | null> {
  const url = new URL(MCP_URL!)
  url.pathname = `${url.pathname.replace(/\/$/, '')}/initial-context`
  try {
    const res = await fetch(url, {headers})
    if (!res.ok) throw new Error(`HTTP ${res.status}`)
    return await res.text()
  } catch (err) {
    console.warn(`Could not fetch initial context, the agent will call the tool instead: ${err}`)
    return null
  }
}

const initialContext = await fetchInitialContext()

let instructions = 'You are a helpful assistant.'
if (initialContext) {
  instructions += `\n\n# Data reference\n\n${initialContext}`
}

// 2. Connect to the Sanity Context MCP server over Streamable HTTP.
const server = new MCPServerStreamableHttp({
  name: 'sanity',
  url: MCP_URL,
  requestInit: {headers},
  clientSessionTimeoutSeconds: 30, // default is 5s, tight for a large schema
  // Hide initial_context only if its content is already in the instructions.
  toolFilter: initialContext
    ? createMCPToolStaticFilter({blocked: ['initial_context']})
    : undefined,
})

await server.connect()
try {
  // 3. Create the agent and run it.
  const agent = new Agent({
    name: 'Assistant',
    instructions,
    mcpServers: [server],
  })
  const result = await run(agent, process.argv[2] ?? 'What content do we have?')
  console.log(result.finalOutput)
} finally {
  await server.close()
}

Run it with a question. Node.js reads the .env file with --env-file:

node --env-file=.env agent.ts "Do you price match?"

A few details differ in the TypeScript SDK:

• connect() and close() are explicit calls, so the example wraps the run in try/finally instead of a context manager.
• The Bearer header goes in requestInit.headers. That option is untyped, so TypeScript doesn't catch a typo there.
• createMCPToolStaticFilter takes blocked, not Python's blocked_tool_names.
• There are two timeouts. clientSessionTimeoutSeconds (default 5) covers connecting and listing tools; timeout (default 60,000 ms) covers each tool call.
• The SDK lists tools again on every turn. Set cacheToolsList: true to list them once per connection.
• If the initial-context fetch fails, the TypeScript example logs a warning and keeps the initial_context tool, so the agent can call it instead. The Python example raises instead.

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_ORGANIZATION_TOKEN"]


async def main():
    # 1. Fetch initial context over 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())

Run the script with the virtual environment active. load_dotenv() reads the .env file:

python agent.py

• Error: Set SANITY_CONTEXT_MCP_URL and SANITY_ORGANIZATION_TOKEN: The environment variables aren't loaded. Run with --env-file=.env.
• SdkHttpError: Version negotiation failed: the server requires authorization (HTTP 401), after Could not fetch initial context ... HTTP 401: The token is missing, invalid, or belongs to another organization.
• 403 from the MCP connection with JSON-RPC error -32007 on an endpoint with a dataset source, or -32006 on an endpoint with only Knowledge Base sources, or the same 403 from the /initial-context fetch with code contextGrantRequired or knowledgeBaseAccessDenied. The messages are "Serving a dataset requires an organization API token with Context access ('sanity.knowledge-base.read'). Create one under your organization's API settings in Manage." (dataset source) and "No access to knowledge base '<knowledge base ID>'. Requires one of: sanity.knowledge-base.read." (Knowledge Base sources only; <knowledge base ID> is a placeholder for the Knowledge Base's ID): On an endpoint with a dataset source, the token isn't an organization API token with Context Viewer permissions. On an endpoint with only Knowledge Base sources, the token has no read access to the Knowledge Base the message names. Project tokens are refused however broad their permissions. Create an organization token as described in Prerequisites.
• Missing credentials. Please pass an `apiKey`, `workloadIdentity`, `adminAPIKey`, or set the `OPENAI_API_KEY` or `OPENAI_ADMIN_KEY` environment variable.: Add OPENAI_API_KEY to the .env file. This surfaces at run(), after the MCP connection has already succeeded.
• [MODULE_TYPELESS_PACKAGE_JSON] Warning: Module type of file:///…/agent.ts is not specified and it doesn't parse as CommonJS.: The agent still runs, but package.json doesn't set the module type. Run npm pkg set type=module.

• 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_ORGANIZATION_TOKEN isn't a valid organization API 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.
• httpx.HTTPStatusError: Client error '403 Forbidden' from the /initial-context fetch, with code contextGrantRequired in the response body: The token isn't an organization API token with Context Viewer permissions. Project tokens are refused however broad their permissions. Create an organization token as described in Prerequisites. A 403 that names a Knowledge Base means the token can't read a Knowledge Base the endpoint serves.