create-agent-with-sanity-context

What this skill does

# 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.

**What this enables:**

- Agents understand the relationships between your content types
- Queries use actual schema fields, not just text similarity
- Results respect your content model (categories, tags, references)
- Semantic search is available when needed, layered on structure

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

Before starting, gather these credentials:

| Credential                | Where to get it                                                                                                                                                                                                                                    |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sanity Project ID**     | Your `sanity.config.ts` or [sanity.io/manage](https://sanity.io/manage)                                                                                                                                                                            |
| **Dataset name**          | Usually `production` — check your `sanity.config.ts`                                                                                                                                                                                               |
| **Sanity API read token** | Run `npx sanity tokens add "Sanity Context" --role=viewer --yes --json` from the project directory (or pass `--project-id=<id>`). Alternatively, create at [sanity.io/manage](https://sanity.io/manage) → Project → API → Tokens with Viewer role. |
| **LLM API key**           | From your LLM provider (Anthropic, OpenAI, etc.) — any provider works                                                                                                                                                                              |

## How Sanity Context Works

The Sanity Context MCP server gives AI agents structured access to Sanity content. The core integration pattern:

1. **MCP Connection**: HTTP transport to the Sanity Context URL
2. **Authentication**: Bearer token using Sanity API read token
3. **Tool Discovery**: Get available tools from MCP client, pass to LLM
4. **System Prompt**: Tell the production agent its role, tone, and boundaries

**MCP URL formats:**

- `https://api.sanity.io/v2026-03-03/context/mcp/:projectId/:dataset` — **Base URL.** No document needed, configure via query params or use as-is.
- `https://api.sanity.io/v2026-03-03/context/mcp/:projectId/:dataset/:slug` — **Document URL.** Applies the configuration from a Sanity Context document.

**Sanity Context documents** (type `sanity.agentContext`) are created in Sanity Studio and configure the MCP endpoint. They have three fields:

| Field              | Schema field   | Purpose                                                                 |
| ------------------ | -------------- | ----------------------------------------------------------------------- |
| **Slug**           | `slug`         | Unique URL identifier — becomes the `:slug` in the MCP URL              |
| **Instructions**   | `instructions` | Domain-specific guidance for the agent, injected into tool descriptions |
| **Content Filter** | `groqFilter`   | A GROQ expression scoping which documents the agent can access          |

This means Studio users can manage agent behavior without touching code — updating instructions or narrowing the content filter takes effect immediately.

**URL query params** override the document's configuration (useful for testing and development):

- `?instructions=<content>` — Override instructions (use `?instructions=""` for a blank slate)
- `?groqFilter=<expression>` — Override the content filter

**The integration is simple**: Connect to the MCP URL, get tools, use them. The reference implementation shows one way to do this—adapt to your stack and LLM provider.

## Available MCP Tools

| Tool              | Purpose                                                         |
| ----------------- | --------------------------------------------------------------- |
| `initial_context` | Get compressed schema overview (types, fields, document counts) |
| `groq_query`      | Execute GROQ queries with optional semantic search              |
| `schema_explorer` | Get detailed schema for a specific document type                |

**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. Studio Setup**         | Configure the context plugin and create Sanity Context documents  | Sanity Studio (separate repo or embedded)                                                                                                               |
| **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                    | `sanity.blueprint.ts` + `functions/` directory — has its own placement constraints (see [Sanity Blueprints & Functions](#sanity-blueprints--functions)) |

A deployed Studio (v5.1.0+) is always required. Not every integration needs the Sanity Context plugin or document—the base MCP URL works without them, so users can start with just agent implementation and add document configuration later—or vice versa. 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 [Sanity Blueprints & Functions](#sanity-blueprints--functions).
2. **Their stack**: What framewo