Content access and security

How the organization token, the MCP endpoint's sources, and groqFilter decide what an agent connected to Context MCP can read.

What an agent can read is decided when it connects, not per query. Your organization token authorizes the connection, the MCP endpoint's sources decide what it serves, and a GROQ filter scopes reads within a dataset source. Context MCP is read-only for both source types and cannot write to your dataset.

Every request carries a bearer token in the Authorization header:

Authorization: Bearer <SANITY_ORGANIZATION_TOKEN>

The endpoint needs an organization API token with Context Viewer permissions, created under Manage > API > Tokens at the organization level. Viewer is the least privilege that works; Editor also works. A project token is refused, however broad its project permissions. Keep the token server-side and never embed it in client code. For custom roles, the grant behind Context Viewer is sanity.knowledge-base.read.

Every check runs on the agent's first request and fails loudly there; an insufficient token never half-works and fails later in tool calls. For every Knowledge Base the endpoint serves, your token must hold read access to that Knowledge Base, and a denied one refuses the connection with a 403 naming it. A check that cannot be answered refuses with a 502 rather than falling open.

Once connected, queries against a dataset source run under Sanity's own service credential, not your token. Attaching the dataset to the MCP endpoint is the standing authorization: attaching it requires the Administrator or Developer role (or a custom role that can create datasets) on the source project, plus unrestricted read access to the dataset, and that decision vets the whole dataset, drafts included, for every app or agent that connects to the endpoint. The endpoint's perspective setting picks what agents read. If a dataset's unpublished content is sensitive, don't attach that dataset.

For the connected agent, groqFilter applies server-side, so nothing in the conversation can change it. It's added to every *[...] selection in the agent's queries, but not to references followed with ->. With no filter set, the agent reads the entire attached dataset in the endpoint's perspective. This includes system documents such as access groups and the deployed schema; set a filter such as _type in ["product", "faq"] to keep them out. The filter selects whole documents; it can't hide fields within a document. Common scopings: public products only, articles in a published state only, customer-facing FAQs and guides.

_type == "product" && public == true
_type == "article" && status == "published"
_type in ["faq", "guide"] && audience == "customer"

An agent connected to a dataset source can read the following:

• Your schema. Document types, field definitions, and references.
• Your content. Published documents by default; the endpoint's perspective setting switches to drafts or raw.
• References. Agents can follow references between documents during a query.

With Knowledge Base sources, groqFilter does not apply. The agent can read everything in the Knowledge Bases the endpoint serves, so scope access by choosing which Knowledge Bases an MCP endpoint serves rather than by filtering within them. Every consumer's token must also hold read access to each Knowledge Base the endpoint serves.

401 Unauthorized means the token is missing, invalid, or belongs to another organization. Confirm it exists in your environment, is read by your agent code, and is sent as Authorization: Bearer <token> rather than as a query parameter or a different header.

403 Forbidden on an endpoint with a dataset source means the token is not an organization API token with Context Viewer permissions. The MCP connection returns JSON-RPC error -32007 and the /initial-context route returns code contextGrantRequired; for the full message, see Authentication in Context MCP reference. Create an organization API token in Manage under API > Tokens at the organization level. A 403 naming a Knowledge Base means your token lacks read access to a Knowledge Base the endpoint serves.

502 Bad Gateway means a permission check could not be answered. Nothing is granted on failure; retry the connection.

Context MCP cannot write to your dataset. If you need an agent that creates or updates documents, run those mutations server-side in your own code after the agent decides what to do. For an MCP-based write path, see the Sanity MCP server.

• Configure a Context MCP endpoint. Choose sources and scope what the agent can read.
• Context MCP reference. groqFilter syntax and every authentication error.