Sanity Agent Toolkit

Collection of resources to help AI agents build better with Sanity. Supports Cursor, Claude Code, VS Code, Lovable, v0, and any other editor/agent compatible with MCP, Agent Skills, or .mdc rules.

---

Features

• Agent rules: 20+ portable .mdc files covering schema design, GROQ, Visual Editing, SEO, localization, migrations, and front-end framework integrations.
• Agent skills: Comprehensive best practices skills for Sanity development, content modeling, SEO/AEO, and experimentation.
• MCP server: Direct access to your Sanity projects (content, datasets, releases, schemas) and agent rules.
• Claude Code plugin: Slash commands and MCP integration for Claude Code users.

---

Get started

Choose your path based on how you want agents to work with Sanity:

1. MCP server — Give your agent always up-to-date rules and full access to your Sanity projects. No local files to maintain. Works with Cursor, VS Code, Claude Code, Lovable, v0, and other MCP-compatible clients.
2. Agent skills — Install best practices skills for Sanity, content modeling, SEO/AEO, and experimentation. Works with Cursor, Claude Code, and any Agent Skills-compatible agent.
3. Claude Code plugin — Adds interactive skills and slash commands on top of MCP for guided workflows.
4. Manual installation — Copy rules locally for offline use. You'll need to update them yourself.

Option 1: Install MCP server (recommended)

Give agents direct access to Sanity projects and always up-to-date agent rules via the MCP server.

Quick install via Sanity CLI

Run in terminal to detect and configure MCP for Cursor, Claude Code and VS Code automatically:

npx sanity@latest mcp configure

Uses your logged-in CLI user for authentication — no manual tokens or OAuth needed.

Client-specific instructions

Cursor

One-click install:

Or manually: Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P) → View: Open MCP Settings → + New MCP Server → add to mcp.json:

{
  "mcpServers": {
    "Sanity": {
      "type": "http",
      "url": "https://mcp.sanity.io"
    }
  }
}

Claude Code

Run in terminal. Authenticate with OAuth on next launch:

claude mcp add Sanity -t http https://mcp.sanity.io --scope user

VS Code

Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P) → MCP: Open User Configuration → add:

{
  "servers": {
    "Sanity": {
      "type": "http",
      "url": "https://mcp.sanity.io"
    }
  }
}

Lovable

Settings → Connectors → Personal connectors → New MCP server → Enter Sanity as name and https://mcp.sanity.io as Server URL → Add & authorize → Authenticate with OAuth.

v0

In the prompt input field, click Prompt Tools → MCPs → Add New → Select Sanity → Authorize → Authenticate with OAuth.

Replit

Go to Integrations Page → scroll to MCP Servers for Replit Agent → Add MCP server → Enter Sanity as name and https://mcp.sanity.io as Server URL → Test & Save → Authenticate with OAuth.

OpenCode

Add to your opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sanity": {
      "type": "remote",
      "url": "https://mcp.sanity.io",
      "oauth": {}
    }
  }
}

Then run: opencode mcp auth sanity

Other clients

For any MCP-compatible client, add https://mcp.sanity.io as the server URL.

If your client doesn't support remote MCP servers, use a proxy like mcp-remote:

{
  "mcpServers": {
    "Sanity": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.sanity.io", "--transport", "http-only"]
    }
  }
}

See the Sanity MCP docs for authorization options and troubleshooting.

Option 2: Install Agent Skills

Install best practices skills that work with any Agent Skills-compatible agent.

npx skills add sanity-io/agent-toolkit

Cursor:

1. Open Cursor Settings (Cmd+Shift+J / Ctrl+Shift+J)
2. Navigate to Rules → Add Rule → Remote Rule (Github)
3. Enter: sanity-io/agent-toolkit

See Option 3 for Claude Code plugin installation.

Option 3: Install Claude Code plugin

For Claude Code users, install the full plugin with skills and slash commands:

1. Add the Sanity marketplace:

/plugin marketplace add sanity-io/agent-toolkit

2. Install the plugin:

/plugin install sanity-plugin@sanity-agent-toolkit

3. Verify installation: Ask Claude Code: "which skills do you have access to?"

You should see the Sanity skills listed.

4. Start using: Use natural language and skills activate automatically:

Use the sanity-scaffold skill to create a blog post schema

Or run /sanity to explore all capabilities.

Option 4: Manual installation

Install the context rules locally to teach your editor Sanity best practices:

1. Create a rules directory: mkdir -p .cursor/rules
2. Copy the contents of the rules/ folder to your project's .cursor/rules/ directory.
3. (Recommended) Copy AGENTS.md to your project root to act as a knowledge router.

---

Capabilities

MCP tools

With MCP connected, your AI can use tools like:

• query_documents — run GROQ queries directly
• create_project — create a new Sanity project
• create_documents_from_markdown — map markdown to Sanity documents
• patch_document_from_json — surgical edits to existing documents
• transform_image — edit images with AI
• list_sanity_rules / get_sanity_rules — load agent rules on demand

See the full list of available tools.

Agent skills

Best practices skills that agents like Claude Code, Cursor, GitHub Copilot, etc. can discover and use automatically. Skills follow the Agent Skills format. See Option 2 for installation.

Skill	Description
sanity-best-practices	GROQ performance, schema design, Visual Editing, images, Portable Text, Studio, TypeGen, localization, and migrations
content-modeling-best-practices	Structured content principles: separation of concerns, references vs embedding, content reuse
seo-aeo-best-practices	SEO/AEO with EEAT principles, structured data (JSON-LD), technical SEO patterns
content-experimentation-best-practices	A/B testing methodology, statistical foundations, experiment design

Getting started flow

The onboarding guide follows three phases:

1. Studio & Schema — Set up Sanity Studio and define your content model
2. Content — Import existing content or generate placeholder content via MCP
3. Frontend — Integrate with your application (framework-specific)

Just say: "Get started with Sanity" to begin.

Context rules

These files provide passive knowledge to the AI, ensuring generated code follows Sanity standards.

Core fundamentals

• sanity-schema.mdc: The "Data > Presentation" philosophy, defineType syntax, and shared fields.
• sanity-groq.mdc: Performance rules, fragment reuse, and the "Golden Rule" of projections.
• sanity-visual-editing.mdc: Implementation of Content Source Maps (Stega) and Presentation Tool.
• sanity-typegen.mdc: TypeScript type generation from schema.
• sanity-project-structure.mdc: File organization for Studio and monorepos.
• sanity-get-started.mdc: Interactive 3-phase onboarding guide.
• sanity-app-sdk.mdc: Building custom apps with the Sanity App SDK, React hooks, and real-time patterns.

Framework rules

• sanity-nextjs.mdc: App Router, defineLive, and metadata handling.
• sanity-remix.mdc: React Router loaders and data fetching patterns.
• sanity-svelte.mdc: SvelteKit hooks and loaders.
• sanity-nuxt.mdc: Nuxt modules and useSanityQuery.
• sanity-astro.mdc: Astro content collections and islands.
• sanity-hydrogen.mdc: Shopify Hydrogen and Sanity Connect.

Best practices

• sanity-migration.mdc: Strategies for importing HTML/Markdown from legacy CMSs.
• sanity-image.mdc: Hotspots, LQIP, and the urlFor builder.
• sanity-studio-structure.mdc: Organizing the Studio sidebar (singletons, groupings).
• sanity-portable-text.mdc: Rendering rich text with custom components.
• sanity-page-builder.mdc: Page builder patterns and block component rendering.
• sanity-localization.mdc: Internationalization patterns.
• sanity-seo.mdc: Metadata, sitemaps, and Open Graph.

Slash commands (Claude Code)

Command	What it does
/sanity	List available skills and help topics
/review	Review code for Sanity best practices
/typegen	Run TypeGen and troubleshoot issues
/deploy-schema	Deploy schema with verification

---

Repository structure

sanity-io/agent-toolkit/
├── AGENTS.md                      # Knowledge router & agent behavior
├── README.md                      # This file
├── rules/                         # Context rules (.mdc)
│   ├── sanity-schema.mdc          # Schema design patterns
│   ├── sanity-groq.mdc            # GROQ query patterns
│   ├── sanity-nextjs.mdc          # Next.js integration
│   └── ...                        # Additional framework rules
├── skills/                        # Agent skills (agentskills.io format)
│   ├── sanity-best-practices/     # Comprehensive Sanity skill
│   │   ├── SKILL.md
│   │   └── rules/                 # Individual rule files
│   ├── content-modeling-best-practices/
│   ├── seo-aeo-best-practices/
│   └── content-experimentation-best-practices/
└── sanity-plugin/                 # Claude Code plugin
    └── commands/                  # Slash commands
        ├── sanity.md              # /sanity help
        ├── review.md              # /review
        ├── typegen.md             # /typegen
        └── deploy-schema.md       # /deploy-schema

---

Resources

• Create Sanity account
• Sanity documentation
• GROQ language reference
• Visual Editing guide
• Sanity TypeGen
• MCP server docs

---

Contributing

Found a better pattern? Missing a framework or best practice?

1. Fork the repo.
2. Update the relevant file:
   • Rules: Edit .mdc files in rules/
   • Skills: Edit rule files in skills/<skill-name>/rules/
3. Run npm run validate to check skill validity.
4. Submit a PR.

---

Support

• Sanity Community (Discord)
• GitHub issues

---

License: MIT