# Sanity setup for PopMCP

You paste one value into PopMCP: a Sanity API token, created in sanity.io/manage under your project's Settings, then API, then Tokens. Then you pick the project to connect.

- Auth: API credentials
- Setup time: 2 min
- API base URL: https://api.sanity.io
- Credentials screen: https://www.sanity.io/manage
- Provider docs: https://www.sanity.io/docs/content-lake/http-auth

## Before you begin

- A Sanity account with a project. Any plan works, including the free one
- The Developer or Administrator role in that project, or something equivalent, because only those roles can make a token
- On the free plan a token can be Viewer, Editor or Deploy Studio. Managing datasets and webhooks needs a role like Developer, which comes with paid plans

## Get your credentials

### 1. Sign in and open your project

Sign in at sanity.io/manage and click the project you want the AI to work with. The short code on the project's page is its project ID, which you only need if PopMCP asks for it.

Screen: https://www.sanity.io/manage

### 2. Open Settings, then API, then Tokens

Go to Settings, then API, and find the Tokens section. Click Add new token.

Screen: https://www.sanity.io/manage

### 3. Name it and choose a role

Enter a name such as PopMCP and choose what the token can do. Editor reads and writes content. Viewer only reads, including drafts. On paid plans, Developer also manages datasets, webhooks and CORS origins. You can set an expiry too: when it passes, Sanity rejects the token for good and you connect again with a new one.

Screen: https://www.sanity.io/manage

### 4. Copy the token

Copy the token right away: Sanity shows it exactly once and cannot show it again. If you lose it, delete it and add a new one.

Screen: https://www.sanity.io/manage

### 5. Paste it into PopMCP and pick your project

In PopMCP, paste the token into API token and connect. PopMCP lists the projects it can reach: pick the one to connect and the PopMCP workspace it goes into. Tools use the production dataset, or your first dataset if there is no production. To change that, open More options and fill in Default dataset. If PopMCP says the token lists no projects, add the project ID there too.

## Fields PopMCP asks for

- API token (accessToken) [required]: In sanity.io/manage open your project, go to Settings, then API, then Tokens, and choose Add new token. Pick Editor to read and write content (on paid plans, Developer also manages datasets and webhooks), then copy the token. Stored encrypted and used server-side only.
- Project ID (projectId): Only needed when the token does not list its project. It is on your project's page in sanity.io/manage.
- Default dataset (dataset): The dataset tools use unless told otherwise. Leave blank for production.

## Verify

PopMCP marks the connection Verified with the project's name (Sanity · Marketing site). Asking the AI to show the document types returns them, with counts, from that project's default dataset.

## Troubleshooting

### "Sanity did not accept this token."

Cause: The token was copied incompletely, has expired or was deleted. An expired Sanity token cannot be reactivated.

Fix: Add a new token under **Settings**, **API**, **Tokens** and paste it whole.

### "This token works but lists no projects."

Cause: The token could not list its projects, which can happen with a tightly limited custom role.

Fix: Open **More options** and paste the project ID from the project's page in sanity.io/manage, or use a token with a broader role.

### "This token cannot open the Sanity project"

Cause: The project ID is wrong, or the token was made in a different project.

Fix: Check the ID on the project's page, or make the token inside that project.

### "This project has no dataset called..."

Cause: The name under **Default dataset** does not exist. The message lists the ones that do.

Fix: Leave the field blank to use production, or type one of the names listed.

### A tool answers "User must have grant..."

Cause: The token's role does not allow that action. Sanity reports this with a 401 even though the token is fine.

Fix: Make a new token with a suitable role, such as Developer for webhooks and datasets, and connect again.

### A query returns an empty list

Cause: GROQ returns an empty result rather than an error for a document type that does not exist, and by default it reads only published content.

Fix: Ask the AI to show the document types first, and to read the drafts perspective if the content is not published yet.

---

Source: https://www.docs.popmcp.com/docs/integrations/sanity/