Compute and AI

Sanity MCP server

Enable AI assistants to interact with your Sanity workspace through the Model Context Protocol (MCP).

The Sanity Model Context Protocol (MCP) server enables AI assistants like Claude Code and Cursor to interact directly with your Sanity projects.

With the MCP server, agents can go beyond code generation and perform advanced content management operations in your Sanity projects—execute GROQ queries, manage releases, and patch documents with full awareness of your schema, eliminating the need to manually supply context.

Installation

The Sanity MCP server is hosted on Sanity's own infrastructure on https://mcp.sanity.io. It follows Anthropic's official MCP specification and works with any MCP-compatible client. It supports authentication through both OAuth (default) and token-based authentication.

Prerequisites:

Quick install via Sanity CLI

The easiest way to get started is using the Sanity CLI. It detects the most common AI-powered editors (Cursor, VS Code, Claude Code) and automatically configures the MCP server for you.

This command uses your logged-in CLI user for authentication, so you don't need to manually authenticate or manage API tokens.

Claude Code

Run the following command in your terminal to add the Sanity MCP server. The next time you run Claude Code, it will have access to the MCP and you can authenticate with OAuth.

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

Cursor

Use the link below to directly install the Sanity MCP server in Cursor. Once installed, you'll be prompted to authorize access.

Add to Cursor →

You can confirm the server is running by opening the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) and running View: Open MCP Settings.

Alternatively, you can manually update your configuration:

  • Open the Command Palette and run View: Open MCP Settings.
  • Select + New MCP Server in the settings pane. This will open your mcp.json file.
  • Add the following configuration:

Once you save the file, Cursor detects the new server and prompts you to authenticate via OAuth to complete the connection.

VS Code

  • Open Visual Studio Code.
  • In the Command Palette (Cmd+Shift+P / Ctrl+Shift+P), run: MCP: Open User Configuration.
  • Update the mcp.json file with the following configuration and save the file:

Once you save the file, VS Code detects the new server and prompts you to authenticate via OAuth to complete the connection.

Lovable

You can add Sanity as a "Personal connector" in Lovable.

  • In Lovable, go to Settings > Connectors > Personal connectors.
  • Click New MCP server.
  • Enter Sanity as the name and https://mcp.sanity.io as the Server URL.
  • Click Add & authorize.
  • Follow the prompt to authenticate with your Sanity account via OAuth.

For more details on managing connectors, see the Lovable MCP documentation.

v0

You can add Sanity as a custom MCP to v0.

  • In the v0 prompt input field, click Prompt Tools (bottom left).
  • Select MCPs, then click Browse MCPs.
  • Scroll to the bottom and click Custom MCP.
  • Enter Sanity as the name and https://mcp.sanity.io as the URL.
  • Select the OAuth tab for authentication.
  • Click Authorize.

Other clients

If your client does not support remote MCP servers, you may be able to use a proxy such as mcp-remote.

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

Authorization

The Sanity MCP server uses OAuth by default to perform operations on your behalf. You may instead provide an API token by setting the Authorization header in your MCP config. When configured with the header, the server will not use OAuth. Tool calls will use the API token in accordance with its role and scoped to its permissions.

You can create API tokens from sanity.io/manage or with the sanity CLI's tokens command. You can also provide a personal token, which will share your role and permissions, as well as link you to any changes in the revision history.

Run commands (or tools)

Once configured and started, authenticate with your Sanity credentials if prompted. You can then use natural language to work with Sanity development tasks, such as:

  • Help me migrate this project to Sanity.
  • Run a GROQ query for all articles written by Mark.
  • Add localization to my article document type.
  • Help me migrate existing content to a new schema shape.
  • List all releases in this dataset.

mcp.sanity.io provides both editorial and development-focused tools for content operations, schema exploration, GROQ query execution, project management tasks such as creating and managing resources like datasets and API keys, and migration assistance. These tools allow your AI assistant to interact with your Sanity data directly.

Available tools

The following is a list of available tools and their uses:

  • get_groq_specification

    Get the GROQ language specification summary

  • get_context

    Get project-specific context for a Sanity project and dataset, including available schemas, releases, and embeddings.

  • get_schema

    Get the full schema of the current Sanity workspace

  • list_workspace_schemas

    Get a list of all available workspace schema names

  • deploy_schema

    Directly deploy schema types to the cloud.

  • create_document_from_json

    Create a new draft document by directly providing its JSON content. Creates a draft (drafts.* prefix) unless releaseId is specified for version creation.

  • create_document_from_markdown

    Create a new draft document from Markdown content. Always creates a draft (drafts.* prefix) unless releaseId is specified for version creation.

  • create_version

    Create a version document (versions.{releaseId}.* prefix) for a specific release. Versions are separate from drafts and published documents, and are used for scheduled release workflows.

  • patch_document

    Apply precise modifications to document fields. When targeting a published document, this creates or updates a draft with the changes (published document remains unchanged). When targeting a draft or version, updates it in place.

  • query_documents

    Query documents from Sanity using GROQ query language

  • generate_image

    Trigger async AI image generation for a document field.

  • transform_image

    Trigger async AI transformation of an existing image.

  • get_document

    Fetch a single document by its exact ID. This is a direct ID lookup only - it does not search, filter, or query. Use when you have a specific document ID and need its full content.

  • publish_document

    Publish a draft document to make it live

  • unpublish_document

    Unpublish a published document (moves it back to drafts)

  • version_replace_document

    Replace the contents of a document version with contents from another document

  • version_discard_document

    Discard a document version from a release (removes it from the release)

  • version_unpublish_document

    Mark a document to be unpublished when the release is run

  • delete_document

    Permanently delete a document and all its drafts

  • list_projects

    Lists all Sanity projects associated with your account

  • get_project_studios

    Retrieves all studio applications linked to a specific Sanity project

  • create_project

    Creates a new Sanity project and initializes it with a dataset and API tokens

  • list_datasets

    Lists all datasets in your Sanity project

  • create_dataset

    Creates a new dataset with specified name and access settings

  • update_dataset

    Modifies a dataset's name or access control settings

  • list_releases

    List content releases in Sanity, optionally filtered by state (active, scheduled, etc)

  • create_release

    Create a new content release in Sanity with an automatically generated ID

  • edit_release

    Update metadata for an existing content release

  • schedule_release

    Schedule a content release to be published at a specific time

  • publish_release

    Publish a release immediately

  • archive_release

    Archive a release that is no longer active

  • unarchive_release

    Restore an archived release

  • unschedule_release

    Remove a previously set schedule from a release

  • delete_release

    Delete a release

  • list_embeddings_indices

    List all available embeddings indices for a dataset

  • semantic_search

    Perform a semantic search on an embeddings index

  • migration_guide

    Retrieve guides for migrating schemas and content from other CMS platforms.

  • search_docs

    Search the official Sanity documentation.

  • read_docs

    Fetch a specific documentation article.

  • list_sanity_rules

    List available best-practice development rules.

  • get_sanity_rules

    Load specific best-practice development rules

Troubleshooting

Authentication issues

If you encounter authentication errors (e.g., 401 Unauthorized), the solution depends on how you installed the server:

Installed via CLI (using token auth)

If you installed the MCP via the Sanity CLI, your authentication relies on a generated token that may have expired or been revoked. To fix this, simply run the configuration command again and re-select your code editor with space:

This will generate a fresh auth token and update your editor's configuration file automatically.

Manually configured (using OAuth)

If you configured the server manually, you are likely using OAuth. Sessions typically expire after 7 days. Your client should prompt you to re-authenticate, but if it gets stuck:

  • VS Code: Run Authentication: Remove Dynamic Authentication Providers from the Command Palette, select the Sanity provider, and restart the server.
  • Cursor: Run Cursor: Clear All MCP Tokens from the Command Palette to reset your session.

Tool availability

If specific tools (like query_documents) are missing or failing, verify that your account has the correct permissions for the project and dataset you are trying to access. The set of available tools may also vary as we release updates to the MCP server.

Support

Join us in the Sanity community to ask questions and discuss our MCP server with other developers in the #mcp-server channel.

Previous

Introduction

Next

Introduction

Was this page helpful?