Sanity Agent Context

Give AI agents structured access to your content. Agent Context is a hosted MCP endpoint that connects AI agents to your Sanity Content Lake, where content is stored as structured, queryable data (not pages or blobs of HTML).

Instead of vectorizing your content into embeddings and hoping similarity search returns the right answer, Agent Context lets agents query your actual data model: filter by fields, traverse references between documents, and combine structured queries with semantic search. Embeddings for exploration, structured queries for precision.

Read the full documentation →

How it works

flowchart LR
  A["Your agent"] <-->|"MCP"| B["Agent Context <br> (hosted by Sanity)"]
  B --> C["Your content in Sanity"]

Loading

You create an Agent Context document in Sanity Studio. This document controls what content your agent can access and generates a unique MCP URL. Your agent connects to that URL with an API token.

Agent Context exposes three MCP tools:

Tool	What it does
initial_context	Returns a compressed schema overview: content types, fields, and document counts
groq_query	Runs GROQ queries with optional semantic search
schema_explorer	Returns the full schema for a specific content type

With these tools, your agent can:

• Look up exact prices, inventory, or metadata (not approximate text matches)
• Filter products by category, size, color, or any field in your schema
• Follow references between documents (a product's brand, a brand's products)
• Combine structured filters with semantic search ("trail running shoes under $150")

Here's a combined query in GROQ:

*[_type == "product" && category == "shoes"]
  | score(text::semanticSimilarity("lightweight trail runner for rocky terrain"))
  | order(_score desc)
  { _id, title, price, category }[0...5]

Structural filter (category == "shoes") for precision. Semantic ranking (text::semanticSimilarity()) for discovery.

Get started

Prerequisites

• A Sanity project with content and a deployed Studio (v5.1.0+)
• A Sanity API read token — create one at sanity.io/manage (Project → API → Tokens) or via CLI:

  npx sanity tokens add "Agent Context" --role=viewer

• An LLM API key (Anthropic, OpenAI, or another provider)

New to Sanity? Start here.

Using skills

If you're using Claude Code, Cursor, or similar, you can install skills that guide your AI assistant through the setup:

npx skills add sanity-io/agent-context --all

Then prompt:

Use the create-agent-with-sanity-context skill to help me build an agent.

The skill walks you through Studio setup, MCP connection, and configuration for your stack (Next.js, SvelteKit, Express, Python, etc).

Other skills help you refine: dial-your-context (tune the Instructions field) and shape-your-agent (craft a system prompt).

Manual setup

1. Install the Studio plugin:

   npm install @sanity/agent-context

   // sanity.config.ts
   import {defineConfig} from 'sanity'
   import {agentContextPlugin} from '@sanity/agent-context/studio'
   
   export default defineConfig({
     // ...existing config
     plugins: [agentContextPlugin()],
   })

2. Create an Agent Context document in Studio and copy the MCP URL.

3. Connect your agent using any MCP-compatible framework. Example with Vercel AI SDK:

   import {createMCPClient} from '@ai-sdk/mcp'
   
   const mcpClient = await createMCPClient({
     transport: {
       type: 'http',
       url: process.env.SANITY_CONTEXT_MCP_URL,
       headers: {
         Authorization: `Bearer ${process.env.SANITY_API_READ_TOKEN}`,
       },
     },
   })

Troubleshooting

Validate the connection — Test that your token and endpoint work:

curl -X POST https://api.sanity.io/v2026-03-03/agent-context/:projectId/:dataset/:slug \
  -H "Authorization: Bearer $SANITY_API_READ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

If this returns a list of tools, you're connected. The full MCP URL is shown in your Agent Context document in Studio.

401 Unauthorized — Your SANITY_API_READ_TOKEN is missing or invalid. Generate a new token at sanity.io/manage → Project → API → Tokens.

No schema or empty results — Agent Context requires a deployed Studio. Run npx sanity deploy. If you've set a content filter, ensure it matches published documents.

Tools not appearing — Verify the MCP URL is correct (project ID, dataset, slug) and that the Agent Context document is published.

Learn more

• Agent Context documentation
• Dataset embeddings
• How to serve content to agents (field guide)
• What is GROQ?
• Content Lake
• Sanity Studio
• Model Context Protocol