# Sanity — how to use (mcp.ai)

Connect your Sanity account and use 21 tools for developer tools straight from your AI agent. Connect with your own API key. Sanity is a headless CMS platform that provides structured content storage and APIs for modern applications.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_sanity?ms=1787293500000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `sanity_add_default_role_to_users`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/sanity`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/sanity/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/sanity/add/default/role/to/users` — Apply organization default role to all users. Use when you need to assign the organization's default role to all existing users in the organization. Requires the resource ID of the organization.
  - body: { resource_id: string }
- `POST https://api.mcp.ai/api/sanity/create/attr/definition` — Tool to create a new user attribute definition in Sanity. Use when you need to define a custom attribute (like 'customer-tier' or 'subscription-level') that can be attached to resources. The key must 
  - body: { key: string, list?: boolean, type: string, read_only?: boolean, description?: string, resource_id: string, resource_type: string }
- `POST https://api.mcp.ai/api/sanity/create/prompt/post` — Send a one-shot prompt to the Sanity Content Agent. Stateless one-shot prompt endpoint. No thread management or message persistence. Ideal for simple, single-turn interactions. Use when you need to se
  - body: { config?: object, format?: string, message: string, instructions?: string, organizationId: string }
- `POST https://api.mcp.ai/api/sanity/delete/attr/definition` — Delete a user attribute definition. Use when you need to remove a custom attribute definition from an organization or project in Sanity. The attribute definition controls how user attributes are struc
  - body: { resource_id: string, definition_id: string, resource_type: string }
- `POST https://api.mcp.ai/api/sanity/delete/document` — Delete a document from Sanity by ID or query. This action is irreversible when purge is true — the document cannot be recovered once permanently deleted. Use when you need to remove a specific documen
  - body: { purge?: boolean, query?: string, params?: object, dataset: string, dry_run?: boolean, project_id: string, return_ids?: boolean, document_id?: string, return_documents?: boolean }
- `POST https://api.mcp.ai/api/sanity/delete/user/attributes` — Delete custom attributes from a Sanity user within an organization. Use this tool when you need to remove specific custom attributes from a user account. The action deletes the attributes specified in
  - body: { attributes: object[], sanity_user_id: string, organization_id: string }
- `POST https://api.mcp.ai/api/sanity/get/document` — Fetch a single document by its ID from Sanity. Use this action when you need to retrieve a specific document using its unique identifier rather than running a GROQ query. Returns the complete document
  - body: { dataset: string, project_id: string, document_id: string }
- `POST https://api.mcp.ai/api/sanity/get/invite/by/token` — Retrieve an invite by its public token. Use this action when you need to fetch details about an invite using the invite token that was shared with the invitee. Returns invite information including sta
  - body: { resourceId: string, inviteToken: string, resourceType: string }
- `POST https://api.mcp.ai/api/sanity/get/org/role` — Retrieve a specific organization role by its ID. Use this action when you need to fetch details about an organization role including its permissions, title, description, and whether it applies to user
  - body: { roleId: string, organizationId: string }
- `POST https://api.mcp.ai/api/sanity/get/permission` — Get a permission for a specific resource. Use when you need to retrieve details about a particular permission including its actions, parameters, and scope. The action retrieves permission information 
  - body: { resource_id: string, resource_type: string, permission_name: string }
- `POST https://api.mcp.ai/api/sanity/get/project` — Retrieve full details for a specific Sanity project by its ID. Returns comprehensive project information including display name, organization, studio host, and timestamps. Use this action when you nee
  - body: { project_id: string }
- `POST https://api.mcp.ai/api/sanity/get/robots` — Tool to get robots with access to a resource. Use when you need to retrieve a list of robots (service accounts) that have been granted access to a specific resource along with their assigned roles. Th
  - body: { limit?: integer, next_cursor?: string, resource_id: string, resource_type: string, include_children?: boolean }
- `POST https://api.mcp.ai/api/sanity/get/role` — Retrieve a specific role for a given resource type and resource ID. Use this action when you need to fetch details about a role including its permissions, title, description, and whether it applies to
  - body: { roleName: string, resourceId: string, resourceType: string }
- `POST https://api.mcp.ai/api/sanity/get/users` — List all users of a resource and their assigned roles. Use when you need to retrieve user information and role assignments for a specific project or organization. Supports pagination via cursor.
  - body: { limit?: integer, next_cursor?: string, resource_id: string, resource_type: string }
- `POST https://api.mcp.ai/api/sanity/list/org/roles` — List all roles available for an organization. Use this action to retrieve all available roles that can be assigned to users within a specific Sanity organization. The organization_id is required to id
  - body: { organization_id: string }
- `POST https://api.mcp.ai/api/sanity/list/user/attributes` — Tool to retrieve user attributes from a Sanity organization. Use when you need to get the attributes (such as roles, permissions, or custom properties) associated with a specific user in a Sanity orga
  - body: { limit?: integer, cursor?: string, sanity_user_id: string, organization_id: string }
- `POST https://api.mcp.ai/api/sanity/query/all/screening` — Execute a GROQ query to fetch all screening documents from Sanity. Uses the Sanity HTTP query API endpoint. Default query retrieves all documents of type 'screening'. Supports optional query parameter
  - body: { query?: string, params?: object, dataset?: string, explain?: boolean, resultSourceMap?: boolean }
- `POST https://api.mcp.ai/api/sanity/query/documents` — Execute an arbitrary GROQ query against a Sanity dataset. GROQ is Sanity's query language for fetching and transforming content. This is a general-purpose query action distinct from any screening-spec
  - body: { query: string, params?: object, useCdn?: boolean, dataset: string, project_id: string, perspective?: string }
- `POST https://api.mcp.ai/api/sanity/update/org/acl` — Tool to assign a role to a member in a Sanity organization. Use when adding or modifying user roles within an organization.
  - body: { role_name: string, sanity_user_id: string, organization_id: string }
- `POST https://api.mcp.ai/api/sanity/update/user/attributes/values` — Update user attribute values for a resource. Use this action to set or update custom attributes for a user within an organization or project. When setting a value for an attribute key that also exists
  - body: { userId: string, attributes: object, resourceId: string, resourceType: string }
- `POST https://api.mcp.ai/api/sanity/validate/credential` — Validate Sanity API credentials by fetching the authenticated user's information. Use this action when you need to verify that an API token is valid and has proper authentication. This action returns 

## Example prompts
- "What can I do in Sanity?"
- "Show me a summary of my Sanity account"

## More
- Page: https://mcp.ai/sanity
- Agent spec (llms.txt): https://mcp.ai/sanity/llms.txt
- Postman collection: https://mcp.ai/sanity/postman.json