Sanity MCP Gateway

Revolutionize your content workflow by empowering AI assistants to orchestrate Sanity data management using conversational input. Create, modify, and semantically query your content assets via natural language commands.

The Sanity MCP Gateway is an implementation of the Model Context Protocol. It bridges your Sanity instances with external generative AI platforms (e.g., Claude, Cursor, specialized tooling) by making the underlying content models intelligible to the AI engine.

✨ Core Capabilities

🧠 Content Acumen: Allows AI to deeply comprehend and navigate your entire content inventory.
⚙️ Workflow Automation: Execute complex content modifications through simple textual directives.
🧱 Structural Integrity: Ensures all automated actions strictly adhere to defined content schemas and validation constraints.
📅 Release Orchestration: Facilitates sophisticated planning and sequencing of content deployment cycles.
🔎 Intent-Based Retrieval: Supports advanced searching based on conceptual meaning rather than relying solely on keyword matching.

🔌 Initial Setup
Cloud Endpoint (Recommended)
Local Server Prerequisites
Integrating the Gateway Configuration
🛠️ Exposed Functionalities
⚙️ Operational Parameters
🔑 Authentication & Authorization
👥 Role Mapping
📦 Runtime Environment Requirements
🛠️ Expedited Setup for NVM Users
🤔 Rationale for Prerequisites
🔍 Common Diagnostic Steps
💻 Development & Debugging

🔌 Initial Setup

Cloud Endpoint (Recommended)

While this document guides local deployment, the hosted cloud instance offers a more robust, production-ready integration path.

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

Consult the Sanity MCP Gateway Documentation for instructions on integrating with Claude Code, Cursor, and other clients.

Local Server Prerequisites

To activate the Gateway locally, perform the following initializations:

Publish Schema Manifest: The Gateway requires access to the current content model definition. Deploy this manifest using one of these methods:

bash cd /path/to/studio npm update sanity npx sanity schema deploy

For automated builds lacking active Sanity session credentials, an authorization token must be supplied:

bash SANITY_AUTH_TOKEN= sanity schema deploy

[!NOTE] Schema deployment necessitates Sanity CLI version 3.88.1 or later for compatibility.

Acquire API Credentials
Project Identifier
Designated Dataset Name
API Access Credential configured with requisite permissions

This Gateway implementation is interoperable with any client adhering to the Model Context Protocol specification. Examples include:

Claude Desktop
Cursor IDE
Visual Studio Code
Bespoke MCP-compliant tooling

Integrating the Gateway Configuration

To instantiate the Sanity MCP Gateway within your consuming application's MCP settings, insert the following structure:

{ "mcpServers": { "sanity": { "command": "npx", "args": ["-y", "@sanity/mcp-server@latest"], "env": { "SANITY_PROJECT_ID": "your-project-id", "SANITY_DATASET": "production", "SANITY_API_TOKEN": "your-sanity-api-token", "MCP_USER_ROLE": "developer" } } } }

Review the Operational Parameters section for a comprehensive listing of required and optional environment variables.

The precise location for this configuration varies based on the host application:

Application	Configuration Repository
Claude Desktop	Dedicated configuration file for the desktop client
Cursor	Workspace or global configuration settings
VS Code	User or workspace settings (extension dependent)
Custom Apps	Consult the specific application's MCP integration documentation

Encountering integration hurdles? Refer to the Runtime Environment Requirements guide.

🛠️ Exposed Functionalities

Context & Initialization

get_initial_context – MANDATORY: Must be invoked first to establish context and retrieve usage guidelines.
get_sanity_config – Fetches current Sanity metadata (projectId, dataset, apiVersion, etc.).

Document Manipulation

create_document – Instantiates a new content document populated with AI-generated material per instructions.
update_document – Modifies an existing document payload using AI-derived content.
patch_document - Executes direct JSON patch operations for granular modifications, bypassing AI generation.
transform_document – Refines existing document data (e.g., text substitutions, style adjustments) while preserving structural integrity.
translate_document – Renders document content into a target language, maintaining format.
query_documents – Executes custom GROQ expressions for content discovery and retrieval.
publish_document – Promotes a draft item to live published status.
unpublish_document – Reverts a live item back to the draft state.
version_replace_document – Overwrites the content of a document version within a release with content from another source document.
version_discard_document – Removes a document instance from consideration within a specified release.
version_unpublish_document – Marks a document for automatic unpublishing upon the activation of its associated release.
delete_document – Permanently erases a document record and all associated draft versions.

Release Cycle Management

list_releases – Enumerates existing content releases, optionally filtering by their current status.
create_release – Establishes a new content release artifact.
edit_release – Modifies descriptive metadata associated with an established release.
schedule_release – Sets a future publication timestamp for a release.
publish_release – Triggers immediate activation of a release.
archive_release – Deactivates and archives a previously active release.
unarchive_release – Reinstates an archived release for potential future use.
unschedule_release – Cancels any pending schedule set for a release.
delete_release – Removes a release record entirely.

Version Control

create_version – Crafts a snapshot version of a document scoped to a particular release.
discard_version – Deletes a specific document version linked to a release.
mark_for_unpublish – Tags a document to be taken offline when its associated release is deployed.

Dataset Administration

list_datasets – Enumerates all accessible datasets within the project context.
create_dataset – Provisions a new data repository.
update_dataset – Adjusts configuration parameters for an existing dataset.

Schema Introspection

get_schema – Retrieves the structure definition, either holistically or for a specified type.
list_workspace_schemas – Fetches a manifest of all defined workspace schema names.

Query Language Support

get_groq_specification – Retrieves a summary of the current GROQ language specification.

Vectorization & Contextual Search

list_embeddings_indices – Lists all active vector indexing structures.
semantic_search – Executes a similarity search against a specified embeddings index.

Project Context Retrieval

list_projects – Lists all Sanity projects linked to the authorizing credentials.
get_project_studios – Fetches studio applications associated with a given project ID.

⚙️ Operational Parameters

The Gateway accepts the following environment variables for configuration:

Variable	Description	Required	Constraint
`SANITY_API_TOKEN`	The secure credential for accessing Sanity APIs.	✅	Token
`SANITY_PROJECT_ID`	The unique identifier for the target Sanity project.	✅	ID
`SANITY_DATASET`	Specifies which data repository partition to operate against.	✅	String
`MCP_USER_ROLE`	Configures the authorization scope: 'developer' grants full capability, 'editor' restricts to content modifications.	✅	Enum
`SANITY_API_HOST`	Overrides the default API endpoint (defaults to https://api.sanity.io).	❌	URL
`MAX_TOOL_TOKEN_OUTPUT`	Sets the upper bound on token volume returned by tool executions (default is 50000). Tune cautiously based on model context window limitations to avoid context bloat.	❌	Integer

[!WARNING] Production Data Interaction Caution
When the Gateway is initialized with credentials permitting write access to a production dataset, the integrated AI entity gains the capacity to execute potentially destructive operations (creation, modification, or irreversible deletion). While security layering is under continuous refinement, users must exercise significant prudence when utilizing write-enabled tokens against live production environments, favoring segregated development/staging datasets for initial validation.

🔑 Authentication & Authorization

The Gateway's successful operation is contingent upon correctly configured API credentials and permissions.

Token Generation Procedure

Via the command line interface:

bash npx sanity tokens add "MCP Gateway Agent" --role

Alternatively, utilizing the Web Portal:

Execute npx sanity manage from your Studio root directory.
Navigate within the project management console: Settings -> API -> Tokens.
Select "Provision new token".
Designate a specific token for the Gateway (e.g., mcp-gateway-token).
Crucially, store this secret immediately, as it is displayed only once!

Mandatory Access Privileges

The necessary permissions for the access token depend on the intended scope of AI activity:

Read-Only Operations: The viewer privilege level is adequate.
Content Mutations (Writes): Roles of editor or developer are advised.
Project-Level Administration (e.g., dataset lifecycle management): The administrator designation may be required.

Dataset Scoping

Public Datasets: Accessible for reading by any unauthenticated client.
Private Datasets: Mandatory requirement for validated token authentication.
Draft and Versioned Content: Restricted exclusively to authenticated principals possessing sufficient role-based access control.

Security Policy Adherence

Institute distinct, granular tokens for each operational environment (e.g., development, testing, live).
Prohibit the inclusion of access tokens within source code repositories (e.g., Git).
Leverage environment variables as the primary mechanism for managing secrets.
Implement a regular credential rotation schedule to mitigate compromise risks.

👥 Role Mapping

The Gateway interprets the MCP_USER_ROLE variable to govern tool enablement:

developer: Grants the agent authorization to invoke the complete suite of available functionalities.
editor: Limits the agent's capabilities to tools focused on content creation and modification, excluding administrative functions.

📦 Runtime Environment Requirements

[!IMPORTANT] Node Version Manager Specific Configuration
Users leveraging Node version management utilities (nvm, mise, fnm, nvm-windows, or similar) must execute the subsequent setup steps. This ensures that the Gateway, when launched, can correctly locate and invoke the Node.js binaries. This is a prerequisite typically required only once and resolves a known limitation in how MCP servers interact with version managers tracked here.

🛠️ Expedited Setup for NVM Users

Explicitly invoke the desired Node.js version manager:

bash # If utilizing nvm nvm use 20 # Or your target version

# If utilizing mise mise use node@20

# If utilizing fnm fnm use 20

Establish the necessary symbolic links (select the appropriate OS command set):

For macOS/Linux Environments:

bash sudo ln -sf "$(which node)" /usr/local/bin/node && sudo ln -sf "$(which npx)" /usr/local/bin/npx

[!NOTE] The use of sudo in this specific context is generally considered safe because:

It only directs symlinks to binaries already installed and verified on your system.

The destination path (/usr/local/bin) is a standard location for user-installed executables.

The links merely point to executables under your control.

The links are easily reversible via the sudo rm command.

For Windows (requires PowerShell executed with Administrator rights):

powershell New-Item -ItemType SymbolicLink -Path "C:\Program Files\nodejs\node.exe" -Target (Get-Command node).Source -Force New-Item -ItemType SymbolicLink -Path "C:\Program Files\nodejs\npx.cmd" -Target (Get-Command npx).Source -Force

Validation Check: bash # Expected output should reflect the version set in step 1 /usr/local/bin/node --version # macOS/Linux "C:\Program Files\nodejs\node.exe" --version # Windows

🤔 Rationale for Prerequisites

When the Gateway initiates execution by calling node and npx executables directly, these utilities reside within isolated environments managed by version controllers. These isolated locations are frequently opaque to standard system processes. The symbolic link creation effectively establishes a persistent, globally accessible reference to the currently active Node environment.

🔍 Common Diagnostic Steps

If Node version changes are frequent:

It is crucial to re-run the symlink updates whenever the active Node version is switched.
Consider scripting this update into your shell initialization files for automation: bash # Example alias for .bashrc or .zshrc alias update-node-symlinks='sudo ln -sf "$(which node)" /usr/local/bin/node && sudo ln -sf "$(which npx)" /usr/local/bin/npx'

To decommission the created symbolic links in the future:

bash

macOS/Linux

sudo rm /usr/local/bin/node /usr/local/bin/npx

Windows (Admin PowerShell)

Remove-Item "C:\Program Files\nodejs\node.exe", "C:\Program Files\nodejs\npx.cmd"

💻 Development & Debugging

Install necessary dependencies:

bash pnpm install

Execute in development mode:

bash pnpm run dev

Compile the production server package:

bash pnpm run build

Run the pre-compiled artifact:

bash pnpm start

Debugging

For deep inspection, utilize the official MCP inspector tool:

bash npx @modelcontextprotocol/inspector \ -e SANITY_API_TOKEN= \ -e SANITY_PROJECT_ID= \ -e SANITY_API_HOST=https://api.sanity.io \ -e SANITY_DATASET= \ -e MCP_USER_ROLE=developer \ node build/index.js

This command launches a web interface designed for monitoring and interactive testing of all exposed functionalities.

sanity-mcp-gateway

Author

sanity-io

Quick Info

Actions

Tags