Build AI agents with structured access to Sanity content via Sanity Context. Use when setting up a Sanity-powered chatbot, connecting an AI assistant to Sanity content, or adding client-side tools to an agent. Covers Studio setup, agent implementation, and advanced patterns. Always use this skill wh

Build an Agent with Sanity Context Give AI agents intelligent access to your Sanity content. Unlike embedding only approaches, Sanity Context is schema aware—agents can reason over your content structure, query with real field values, follow references, and combine structural filters with semantic search. Sanity Context gives agents your schema and teaches them GROQ, but it can't know your domain. You close that gap through the Instructions field (dataset specific query guidance) and optionally the system prompt (agent behavior and tone). Three actors in this workflow: You — the agent executing this skill, helping the user set things up The user — the human you're working with, who knows their domain and data The production agent — the agent being built, which will serve end users What You'll Need The agent code needs only three values: Value Where to get it MCP endpoint URL ( SANITY CONTEXT MCP URL ) Shown on the endpoint in the Context app once it's created ([Step 1]( step 1 create the mcp endpoint)) Organization API token ( SANITY ORGANIZATION TOKEN ) [Manage](https://www.sanity.io/manage/org/api/tokens) → organization → API → Tokens → Add API token , then under Organization permissions check Context . Choose Viewer for an agent that only reads; choose Editor if it also records Insights (Step 3). Project tokens do not work. LLM API key From your LLM provider (Anthropic, OpenAI, etc.) — any provider works Setup also involves: Requirement When Where to get it Context enabled Always An organization admin enables it from the organization's [Labs page](https://www.sanity.io/manage/org/labs) in Manage. This also enables Knowledge Bases Sanity project and dataset GROQ mode Picked when creating the endpoint; also where the schema is deployed from ( sanity.config.ts ) Organization ID Insights [Manage](https://www.sanity.io/manage) → organization settings, or the organization's URL The organization token is a server side secret. It must never reach the browser. How Sanity Context Works The Sanity Context MCP server gives AI agents structured, read only access to Sanity content. The core integration pattern: 1. Initial Context : Fetch the initial context (the schema in GROQ mode, the Knowledge Base outline in Knowledge Base mode) via the /initial context HTTP endpoint and inject it into the system prompt 2. MCP Connection : HTTP transport to the MCP endpoint URL 3. Authentication : Bearer token using the organization API token 4. Tool Discovery : Get available tools from MCP client, pass to LLM 5. System Prompt : Tell the production agent its role, tone, and boundaries Two retrieval modes. The endpoint's content source decides which one it serves: GROQ mode (a dataset source): the agent queries the live dataset with GROQ, guided by the schema. Fits structured, consistent content where the schema tells the agent where to look: catalogs, articles, FAQs. For in between content (a catalog with useful details in prose fields), enable [dataset embeddings](https://www.sanity.io/docs/content lake/dataset embeddings) and stay in GROQ mode. Knowledge Base mode (Knowledge Base sources, beta): the agent reads a pre built index built ahead of time from datasets, websites, and files. Fits answers spread across prose from several places, where finding the answer is the hard part. See [Context retrieval modes](https://www.sanity.io/docs/ai/sanity context retrieval modes). An endpoint serves one mode. If it has both a dataset source and Knowledge Base sources, the dataset wins and the Knowledge Bases are ignored, with no error. Ask the user which fits; GROQ mode is the default for content that lives in a Sanity dataset. MCP endpoints are created in the Context app in the Sanity Dashboard. Each endpoint has these fields: Field Purpose Title Human readable label. The agent also sees it as the heading of its initial context Name URL identifier (lowercase, numbers, hyphens). Unique in the organization and immutable after creation Content source What the endpoint serves: a dataset (GROQ mode) or one or more Knowledge Bases (Knowledge Base mode) Instructions Domain specific guidance for the agent, injected into the initial context GROQ filter A GROQ filter expression scoping which documents the agent can read. GROQ mode only MCP URL: The Context app shows the URL once the endpoint is created. Changes to instructions or the filter in the Context app take effect without redeploying the agent. If the agent caches /initial context (recommended below), instruction changes show up when that cache refreshes. URL query params apply per request (useful for testing and development): ?instructions=<content — Overrides the endpoint's instructions (an empty ?instructions= gives a blank slate) ?groqFilter=<expression — Narrows the endpoint's filter. The saved filter always still applies; the two are combined with && ?perspective=drafts raw <releaseId — Content perspective. Defaults to published Initial context: Always fetch the initial context via the /initial context HTTP endpoint and inject it into the system prompt. This gives a significant latency improvement on the first message—the agent already knows the schema and available tools without needing a tool call. It also enables better prompt caching since the schema prefix is stable across conversations. Append /initial context to the MCP URL path (before any query params), using the same auth header: In a long running server, cache the result with a short TTL (the reference implementation uses 5 minutes) and include it in your system prompt. A short TTL keeps schema, Instructions, and Knowledge Base rebuilds flowing through without a redeploy. Critical: the model must always get the initial context. It's either inlined into the system prompt, or available as the initial context tool. Never neither: without it the agent has no schema or outline and guesses. Fetch succeeded and inlined → remove the initial context tool, so the model doesn't fetch it again. Fetch failed, or you don't control the system prompt (e.g. a third party MCP client) → keep the initial context tool; the agent calls it on the first message. Never remove the tool unless the payload is actually in the system prompt. Available MCP Tools The endpoint's mode decides which tools it serves: GROQ mode: tools to read the schema, run GROQ queries (with optional semantic search), and read large array fields. Queries are always subject to the endpoint's GROQ filter. Knowledge Base mode: tools to search and read Knowledge Base entries. Both modes serve initial context : the schema overview (GROQ mode) or the Knowledge Base outline, plus the endpoint's Instructions. It's the same payload as the /initial context HTTP endpoint. Don't hardcode the tool list. The set grows over time, so take it from the MCP client ( mcpClient.tools() or tools/list ). For what each tool does, see [Context MCP tools](https://www.sanity.io/docs/ai/sanity context mcp tools). For development and debugging: The general Sanity MCP provides broader access to your Sanity project (schema deployment, document management, etc.). Useful during development but not intended for customer facing applications. Before You Start: Understand the User's Situation A complete integration has four distinct components that may live in different places: Component What it is Examples 1. MCP Endpoint A deployed schema (GROQ mode) or a built Knowledge Base, plus an endpoint created in the Context app Studio (v5.1.0+) for the schema deploy, Context app in the Sanity Dashboard for Knowledge Bases and the endpoint 2. Agent Implementation Code that connects to Sanity Context and handles LLM interactions Next.js API route, Express server, Python service, or any MCP compatible client 3. Frontend UI for users to interact with the agent Chat widget, search interface, CLI—or none for backend services 4. Functions Scheduled classification via Sanity Blueprints (only with Insights, Step 3) sanity.blueprint.ts + functions/ directory — has its own placement constraints (see [Insights: Project Structure](references/conversation classification.md project structure)) An MCP endpoint is always required, backed by a deployed schema (GROQ mode, Studio v5.1.0+) or a built Knowledge Base: the agent has nothing to connect to without them. Frontend depends on the use case (many agents run as backend services or integrate into existing UIs). Before writing any code, inspect the project to understand: 1. Project layout : Read the top level package.json (check for workspaces or a pnpm workspace.yaml ), locate the lockfile, and map out the distinct apps/packages. This determines where sanity.blueprint.ts and functions/ will go — see [Insights: Project Structure](references/conversation classification.md project structure). 2. Their stack : What framework/runtime? (Next.js, Remix, Node server, Python, etc.) 3. Their AI library : Vercel AI SDK, LangChain, direct API calls, etc. 4. Their domain : What will the agent help with? (Shopping, docs, support, search, etc.) 5. Which components they need help with : They may only need one or two. Components in different repos (most common): You may only have access to one component. Complete what you can, then tell the user what steps remain for the other repos. Co located components : All in the same project—work through them based on what the user wants to tackle first. No Studio in the codebase? For GROQ mode, ask the user whether the schema is already deployed from a Studio elsewhere. If it isn't, it has to be deployed bef

create-agent-with-sanity-context