> For AI agents: the complete Sanity documentation index is available at [https://www.sanity.io/docs/llms.txt](https://www.sanity.io/docs/llms.txt). # Connect Sanity Context with OpenAI Agents SDK Connect Sanity Context to a Python or TypeScript agent using the OpenAI Agents SDK with built-in MCP support. The OpenAI Agents SDK ([openai-agents](https://github.com/openai/openai-agents-python) for Python, [@openai/agents](https://github.com/openai/openai-agents-js) for TypeScript) builds agents with built-in MCP support and discovers MCP tools automatically. This guide shows you how to connect an Agents SDK agent to [Sanity Context](https://www.sanity.io/docs/context/introduction). You'll build a script that loads your schema or Knowledge Base outline into the agent's instructions, connects to your Context MCP endpoint, and answers a question about your content. The same code works whether the endpoint uses Knowledge Base sources, a dataset source, or both. With Knowledge Base sources only, the tools are `knowledge_base_search` and `knowledge_base_read` instead of the dataset source tools, and the initial context is the Knowledge Base outline instead of your schema. With both source types, the endpoint serves the dataset source tools and the Knowledge Base source tools, and its initial context contains both the schema overview and the Knowledge Base outline. See [Context MCP source types](https://www.sanity.io/docs/context/source-types). ## Prerequisites To follow this guide, you need: - **Context MCP endpoint URL**: Shown on the MCP endpoint in the Context app in the Sanity Dashboard. To create an MCP endpoint, see [Configure a Context MCP endpoint](https://www.sanity.io/docs/context/configure-mcp), or expand **Create the endpoint with the Sanity CLI (optional)** at the end of this section. - **Organization API token**: Create one in [Manage](https://www.sanity.io/manage/org/api/tokens) under **API > Tokens** at the organization level. Under **Organization permissions**, select **Context** with the **Viewer** role. Project tokens are refused. - **OpenAI API key**: The SDK reads it from `OPENAI_API_KEY`. - **Python 3.10 or later**, required by `openai-agents`, or **Node.js 22.18 or later** for TypeScript. Node.js 22.18 and later run `.ts` files directly. You can create a Knowledge Base and an MCP endpoint from the Sanity CLI instead of the Dashboard. If you haven't signed in, run `npx sanity@latest login`. You still create the organization token in Manage. Replace `ORGANIZATION_ID`, `PROJECT_ID`, and `KNOWLEDGE_BASE_ID` with your own values: **npm** ```shell # Create a Knowledge Base. The command prints its ID. npx sanity@latest context create --organization ORGANIZATION_ID --title "Support" --description "Answers to customer support questions" # Add sources: a dataset query, files, or a website to crawl (--url) npx sanity@latest context sources create KNOWLEDGE_BASE_ID --sanity-project-id PROJECT_ID --sanity-dataset-id production --query '*[_type == "article"]' npx sanity@latest context sources create KNOWLEDGE_BASE_ID --file ./returns-policy.pdf # Build it, then review anything the build flagged npx sanity@latest context build KNOWLEDGE_BASE_ID --watch npx sanity@latest context issues list KNOWLEDGE_BASE_ID --status open # Create the MCP endpoint and check that it's ready npx sanity@latest context mcp create support --title "Support" --organization ORGANIZATION_ID --knowledge-base KNOWLEDGE_BASE_ID npx sanity@latest context mcp status support --organization ORGANIZATION_ID ``` **pnpm** ```shell # Create a Knowledge Base. The command prints its ID. pnpm dlx sanity@latest context create --organization ORGANIZATION_ID --title "Support" --description "Answers to customer support questions" # Add sources: a dataset query, files, or a website to crawl (--url) pnpm dlx sanity@latest context sources create KNOWLEDGE_BASE_ID --sanity-project-id PROJECT_ID --sanity-dataset-id production --query '*[_type == "article"]' pnpm dlx sanity@latest context sources create KNOWLEDGE_BASE_ID --file ./returns-policy.pdf # Build it, then review anything the build flagged pnpm dlx sanity@latest context build KNOWLEDGE_BASE_ID --watch pnpm dlx sanity@latest context issues list KNOWLEDGE_BASE_ID --status open # Create the MCP endpoint and check that it's ready pnpm dlx sanity@latest context mcp create support --title "Support" --organization ORGANIZATION_ID --knowledge-base KNOWLEDGE_BASE_ID pnpm dlx sanity@latest context mcp status support --organization ORGANIZATION_ID ``` **yarn** ```shell # Create a Knowledge Base. The command prints its ID. yarn dlx sanity@latest context create --organization ORGANIZATION_ID --title "Support" --description "Answers to customer support questions" # Add sources: a dataset query, files, or a website to crawl (--url) yarn dlx sanity@latest context sources create KNOWLEDGE_BASE_ID --sanity-project-id PROJECT_ID --sanity-dataset-id production --query '*[_type == "article"]' yarn dlx sanity@latest context sources create KNOWLEDGE_BASE_ID --file ./returns-policy.pdf # Build it, then review anything the build flagged yarn dlx sanity@latest context build KNOWLEDGE_BASE_ID --watch yarn dlx sanity@latest context issues list KNOWLEDGE_BASE_ID --status open # Create the MCP endpoint and check that it's ready yarn dlx sanity@latest context mcp create support --title "Support" --organization ORGANIZATION_ID --knowledge-base KNOWLEDGE_BASE_ID yarn dlx sanity@latest context mcp status support --organization ORGANIZATION_ID ``` **bun** ```shell # Create a Knowledge Base. The command prints its ID. bunx sanity@latest context create --organization ORGANIZATION_ID --title "Support" --description "Answers to customer support questions" # Add sources: a dataset query, files, or a website to crawl (--url) bunx sanity@latest context sources create KNOWLEDGE_BASE_ID --sanity-project-id PROJECT_ID --sanity-dataset-id production --query '*[_type == "article"]' bunx sanity@latest context sources create KNOWLEDGE_BASE_ID --file ./returns-policy.pdf # Build it, then review anything the build flagged bunx sanity@latest context build KNOWLEDGE_BASE_ID --watch bunx sanity@latest context issues list KNOWLEDGE_BASE_ID --status open # Create the MCP endpoint and check that it's ready bunx sanity@latest context mcp create support --title "Support" --organization ORGANIZATION_ID --knowledge-base KNOWLEDGE_BASE_ID bunx sanity@latest context mcp status support --organization ORGANIZATION_ID ``` `mcp create` prints the endpoint URL to use as `SANITY_CONTEXT_MCP_URL`. To serve a live dataset through a dataset source instead, replace `--knowledge-base KNOWLEDGE_BASE_ID` with `-p PROJECT_ID -d production`. See the [Context CLI command reference](https://www.sanity.io/docs/cli-reference/cli-context) for every flag. ## Install dependencies In a new project directory, install the Agents SDK for your language: #### TypeScript **npm** ```shell npm install @openai/agents zod ``` **pnpm** ```shell pnpm add @openai/agents zod ``` **yarn** ```shell yarn add @openai/agents zod ``` **bun** ```shell 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: **CLI** ```sh npm pkg set type=module ``` #### Python **CLI** ```sh 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`. ## Set environment variables Create a `.env` file next to `agent.ts` or `agent.py`. In TypeScript, Node.js reads it with `--env-file`; in Python, `load_dotenv()` reads it. Replace each placeholder with your own value: **.env** ```sh SANITY_CONTEXT_MCP_URL=YOUR_MCP_ENDPOINT_URL SANITY_ORGANIZATION_TOKEN=YOUR_ORGANIZATION_TOKEN OPENAI_API_KEY=YOUR_OPENAI_API_KEY ``` ## Create the agent Create `agent.ts` or `agent.py` next to `.env`. The script works in three stages: 1. **Fetch initial context** from the `/initial-context` HTTP endpoint and add it to the agent's instructions. The agent starts with a compressed schema or Knowledge Base outline, which saves a tool call on every conversation. For details, see [Inline initial context into your system prompt](https://www.sanity.io/docs/context/inline-initial-context). 2. **Connect to the MCP endpoint** with `MCPServerStreamableHttp`, authenticating with your organization API token. The SDK discovers tools automatically when you pass the server in `mcp_servers` (Python) or `mcpServers` (TypeScript). A static tool filter, `create_static_tool_filter` (Python) or `createMCPToolStaticFilter` (TypeScript), blocks the `initial_context` tool because its payload is already in the instructions. 3. **Create the agent and run it** with `Runner.run` (Python) or `run()` (TypeScript). The agent makes tool calls as it explores your content. Without a `model` argument, `Agent` uses the SDK's default model and reads credentials from `OPENAI_API_KEY`, so a missing key fails at this stage, after the MCP connection has already succeeded. #### TypeScript **agent.ts** ```typescript 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 { 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`: **CLI** ```sh 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. #### Python **agent.py** ```python 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: **CLI** ```sh python agent.py ``` The agent calls the Context MCP tools to explore your content, then prints its answer to the terminal. If the run fails, match the message against the lists in [Troubleshoot common errors](https://www.sanity.io/docs/context/connect-openai-agents-sdk). ## Troubleshoot common errors These are the most common errors and how to fix them: #### TypeScript - `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 ''. Requires one of: sanity.knowledge-base.read." (Knowledge Base sources only; `` 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](https://www.sanity.io/docs/context/connect-openai-agents-sdk). - `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`. #### Python - `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](https://www.sanity.io/docs/context/connect-openai-agents-sdk). A 403 that names a Knowledge Base means the token can't read a Knowledge Base the endpoint serves. ## Next steps - [Sanity Context patterns and best practices](https://www.sanity.io/docs/context/best-practices): Production patterns for public assistants, personalized agents, and multi-backend setups. - [Inline initial context into your system prompt](https://www.sanity.io/docs/context/inline-initial-context): Control what the inlined payload contains and keep it fresh in long-running agents. - [Add insights to Sanity Context](https://www.sanity.io/docs/context/insights): Track and analyze agent conversations. - [AI shopping assistant walkthrough](https://www.sanity.io/sanity-context-ecommerce): A full reference implementation using Next.js and the Vercel AI SDK.