Merge Unified's Sanity integration Merge Agent Handler's Sanity MCP server

Connect your AI Agents to Sanity in minutes

Merge lets you securely connect your agents to Sanity and thousands of tools instantly

Start building for free

Read docs

Sanity

Learn more about Merge Agent Handler

Available tools

list_cors_origins

List CORS origins allowed to call the project's API from a browser.

create_cors_origin

Whitelist an origin (e.g., https://example.com) to call the API from a browser.

delete_cors_origin

Remove a CORS origin by its numeric ID. Use listcorsorigins to find IDs.

list_datasets

List all datasets in a project with their ACL mode and creation time.

create_dataset

Create a new dataset in a project. Name must be lowercase alphanumeric with '_' or '-'.

update_dataset

Update a dataset's ACL mode to 'public' or 'private'.

delete_dataset

Delete a dataset permanently. All documents inside are removed. This cannot be undone.

query_documents

Run a GROQ query over a dataset. Use bound $params for user input. Supports pagination via GROQ slicing like [0...100].

get_document

Fetch one or more documents by ID, bypassing any CDN cache. Use query_documents to discover IDs.

create_document

Create a new document. The document must include a 'type' field. If 'id' is omitted, Sanity assigns one.

create_or_replace_document

Create a document, or fully replace an existing document with the same id. Use getdocument first to check existence.

patch_document

Apply a partial update (set / unset / inc / dec / setIfMissing) to an existing document. Use query_documents to find IDs.

delete_document

Delete a document by ID. For drafts, prefix the ID with 'drafts.'. This cannot be undone.

get_document_history

Retrieve a document's state at a specific revision or point in time. Provide either 'revision' or 'time'.

list_projects

List all Sanity projects the authenticated user is a member of.

get_project

Get details for a specific Sanity project. Uses project_id from credentials if not provided.

update_project

Update a project's display name, studio host, or metadata. Use list_projects to find valid IDs.

list_project_features

List feature flags enabled for a project, such as private datasets or scheduled publishing.

validate_credential

Validate Sanity API token and project ID by fetching the configured project.

list_webhooks

List all webhooks configured for a project.

get_webhook

Get a webhook's full configuration including filter, projection, and headers.

create_webhook

Create a webhook that fires on document create/update/delete events matching a GROQ filter.

update_webhook

Update a webhook's configuration. Only provided fields are changed.

delete_webhook

Delete a webhook permanently. Use list_webhooks to find IDs.

list_webhook_attempts

List delivery attempts for a webhook including HTTP status codes. Use offset from page_info for the next page.

View all tools by creating a free account See more tools

How to set up Merge Agent Handler

In an mcp.json file, add the configuration below, and restart Cursor.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5      "headers": {
6        "Authorization": "Bearer yMt*****"
7      }
8    }
9  }
10}
11

Copy Code

Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.

Make sure Claude is using the Node v20+.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote@latest",
8        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9        "--header",
10        "Authorization: Bearer ${AUTH_TOKEN}"
11      ],
12      "env": {
13        "AUTH_TOKEN": "yMt*****"
14      }
15    }
16  }
17}

Copy Code

Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.

Learn more in the official documentation ↗

1{
2    "mcpServers": {
3      "agent-handler": {
4        "command": "npx",
5        "args": [
6          "-y",
7          "mcp-remote@latest",
8          "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9          "--header",
10          "Authorization: Bearer ${AUTH_TOKEN}"
11        ],
12        "env": {
13          "AUTH_TOKEN": "<ah-production-access-key>"
14        }
15      }
16    }
17  }

Copy Code

In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".

You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.

Learn more in the official documentation ↗

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "agent-handler-auth",
6      "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7      "password": true
8    }
9  ],
10  "servers": {
11    "agent-handler": {
12      "type": "stdio",
13      "command": "npx",
14      "args": [
15        "-y",
16        "mcp-remote@latest",
17        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18        "--header",
19        "Authorization: Bearer ${input:agent-handler-auth}"
20      ]
21    }
22  }
23}

Copy Code

FAQs on using Merge's Sanity MCP server

What is a Sanity MCP?

It's an MCP server that connects your agents to Sanity's headless CMS through tools. Your agents can invoke these tools to query documents with GROQ, create and update content, manage datasets, register webhooks, and review document history, and more.

Sanity offers an official MCP server, but you can also use one from a third-party platform, like Merge Agent Handler.

How can I use the Sanity MCP server?

The use cases naturally depend on the agent you've built, but here are a few common ones:

Content retrieval for AI-powered responses: When a support bot receives a question, an agent queries Sanity documents using GROQ to find the most relevant knowledge base article and returns the content directly in the response, without requiring a separate search service or manual content lookup

Automated content creation from external events: When a product changelog entry is merged in GitHub, an agent creates a corresponding Sanity document with the release title, description, and date, keeping the website's changelog section current without any manual CMS editing

Webhook provisioning for new projects: When a new Sanity project is spun up, an agent registers the necessary webhooks pointing to the correct downstream endpoints, automating setup that would otherwise require a developer to configure manually in the Sanity dashboard

Content audit for compliance reviews: When a compliance review is triggered, an agent retrieves the document history for a set of Sanity content items, compiling a record of what changed and when, and posts the audit summary to a designated Slack channel for review

What are popular tools for Sanity's MCP server?

Here are some of the most commonly used tools:

query_documents: executes a GROQ query against a Sanity dataset and returns matching documents. Useful for agents that need to search or filter content before deciding what to retrieve, create, or surface in a response

get_document: retrieves a specific Sanity document by ID, including all fields and their current values. Call this when an agent needs the full content of a known document before displaying, summarizing, or updating it

create_document: adds a new document to a Sanity dataset with the specified type and field values. Good for workflows that need to land content in the CMS automatically when triggered by an external event

patch_document: applies targeted field-level updates to an existing Sanity document without overwriting the full record. Use this when an agent needs to update a specific field, such as a publication status or revised body copy, while leaving other content intact

create_webhook: registers a webhook on a Sanity dataset so that an external system receives notifications when documents change. Helpful when an agent handles project setup and needs Sanity to push content events to a downstream system rather than polling for updates

get_document_history: returns the revision history for a specific document, including timestamps and field-level changes. Call this when an agent needs to audit content changes or identify when a specific edit was made

What makes Merge Agent Handler's Sanity MCP server better than alternative Sanity MCP servers?

Here is why Merge Agent Handler is worth considering alongside or instead of the official Sanity MCP server:

Enterprise-grade security and DLP: Merge Agent Handler includes built-in data loss prevention controls that let you block or redact sensitive fields before they reach an agent. For Sanity, this means you can prevent draft content, unpublished posts, or internal documentation from being surfaced to agents that should only see published material

Managed authentication and credentials: Merge stores and refreshes your Sanity tokens on your behalf. You never pass raw credentials to an agent or manage token rotation as projects and datasets change

Real-time observability and audit trail: Every Sanity tool call is logged with the timestamp, tool name, input parameters, and response. You can see exactly which documents an agent queried, created, or modified across any dataset without adding instrumentation to your content pipeline

Tool Packs and controlled access: Tool Packs let you define exactly which Sanity tools each agent can reach. A content retrieval agent gets query_documents and get_document. It never gets access to delete_document, delete_dataset, or other write tools it has no reason to use

How can I start using Merge Agent Handler's Sanity MCP server?

You can take the following steps:

1. Create or log into your Merge Agent Handler account.

2. Install the Merge CLI by running pipx install merge-api, then run merge configure to link the CLI to your Merge account and merge login to authenticate your session.

3. Register the Agent Handler MCP server with Claude Code by running claude mcp add --transport http agent-handler https://ah-api.merge.dev/mcp, then open Claude Code and run /mcp to confirm agent-handler appears with a connected status.

4. Select agent-handler from the MCP list. This opens a browser window where you select which integrations to authenticate. Choose Sanity and complete the OAuth flow. Merge stores and manages the credentials going forward.

5. Open a Claude Code session and start querying Sanity data directly. The first time you use a Sanity tool, a Magic Link may appear to complete connector authentication.

If you want to connect Merge Agent Handler's Sanity MCP with internal or customer-facing agentic products, you can follow the steps in our docs.