Define Context with Blueprints

Define Knowledge Bases and MCP endpoints as code with defineContextKnowledgeBase and defineContextMcpEndpoint.

Context gives your AI agents Knowledge Bases built from your content, and Model Context Protocol (MCP) endpoints to connect to them. With Blueprints, you can manage both as code, deployed alongside your other infrastructure.

In this guide, you'll define a Knowledge Base and an MCP endpoint with Blueprints and deploy the blueprint to Sanity.

Prerequisites:

• The latest version of the sanity CLI is recommended to interact with Blueprints. You can always run the latest CLI commands with npx sanity@latest.
• An organization with Context and permission to manage it. Administrators and Developers can create Knowledge Bases and manage MCP endpoints.
• @sanity/blueprints 0.31.0 or later.

npx sanity@latest blueprints init . --type ts --organization-id YOUR_ORGANIZATION_ID --stack-name production

pnpm dlx sanity@latest blueprints init . --type ts --organization-id YOUR_ORGANIZATION_ID --stack-name production

yarn dlx sanity@latest blueprints init . --type ts --organization-id YOUR_ORGANIZATION_ID --stack-name production

bunx sanity@latest blueprints init . --type ts --organization-id YOUR_ORGANIZATION_ID --stack-name production

Use defineContextKnowledgeBase and defineContextMcpEndpoint to declare your Knowledge Bases and the endpoints that serve them. A blueprint configures these resources, not their content. A Knowledge Base declared in a blueprint starts empty: you add its sources (uploads, websites, and datasets) and build it in the Context dashboard or through the API. A deploy never starts a build, and an endpoint can't serve a Knowledge Base until it has been built.

This blueprint defines a Knowledge Base, and an MCP endpoint that serves it alongside a dataset:

import {defineBlueprint, defineContextKnowledgeBase, defineContextMcpEndpoint} from '@sanity/blueprints'

export default defineBlueprint({
  resources: [
    defineContextKnowledgeBase({
      name: 'product-docs',
      title: 'Product docs',
      description: 'Everything about the product',
    }),
    defineContextMcpEndpoint({
      name: 'support-agent',
      title: 'Support agent',
      sources: [
        {type: 'knowledge-base', id: '$.resources.product-docs'},
        {type: 'dataset', id: 'abc123.production'},
      ],
      groqFilter: '_type in ["article", "faq"]',
      instructions: 'Answer support questions using the product docs.',
    }),
  ],
})

defineContextKnowledgeBase takes:

• name: The resource name, unique within the blueprint. Other resources refer to the Knowledge Base as $.resources.<name>. The Knowledge Base itself has no name, only a title, and changing name counts as removing it (see "Remove a single resource").
• title: Up to 100 characters.
• description: What the Knowledge Base covers, up to 2,000 characters.

defineContextMcpEndpoint takes:

• name: The name in the URL agents connect to (…/mcp/support-agent). Lowercase letters, digits, and single hyphens, up to 64 characters. by-name and mcp followed by eight letters or digits are reserved. Changing it deletes the endpoint and creates a new one with a new URL.
• title: Up to 100 characters.
• sources: What the endpoint serves, between one and 100 sources, with any number of Knowledge Bases and at most one dataset.
• groqFilter: Optional. Limits which documents the dataset source serves, up to 10,000 characters. Only allowed with a dataset source.
• instructions: Optional. Instructions for connecting agents, up to 10,000 characters.

A source is one of:

• A Knowledge Base in the same blueprint: {type: 'knowledge-base', id: '$.resources.<name>'}. You can also pass the value defineContextKnowledgeBase returns.
• An existing Knowledge Base the blueprint doesn't manage: {type: 'knowledge-base', id: 'kb…'}. The blueprint only points at it, and never changes or removes it.
• A dataset: {type: 'dataset', id: '<projectId>.<datasetName>'}, with three optional settings:
  • workspace: The Studio workspace whose schema agents use, by name. Defaults to the Studio's first workspace.
  • perspective: published, drafts, or raw. Defaults to published.
  • semanticSearch: false turns semantic search off. By default, agents use it while the dataset has embeddings enabled.

An endpoint serves only the sources it lists, and one Knowledge Base can serve several endpoints.

To attach a dataset, you need to be an administrator of its project and able to read the whole dataset, as in the dashboard. CI deploy tokens from sanity blueprints mint-deploy-token can manage Knowledge Bases and endpoints but can't read dataset contents, so deploy an endpoint with a dataset source with your own login.

To bring an existing Knowledge Base or endpoint under the blueprint, attach it by its ID (kb… or mcp…) in its definition:

defineContextKnowledgeBase({
  name: 'product-docs',
  title: 'Product docs',
  description: 'Everything about the product',
  lifecycle: {ownershipAction: {type: 'attach', id: 'kbABC123xyz'}},
})

The next deploy applies the blueprint's values to it, and from then on the blueprint manages it like a resource it created, including when you remove it or destroy the stack. To use a Knowledge Base without managing it, list it as a source by its ID instead. For the other lifecycle options, see the lifecycle field in the Blueprint configuration reference.

Next, deploy the blueprint.

npx sanity blueprints deploy

pnpm dlx sanity blueprints deploy

yarn dlx sanity blueprints deploy

bunx sanity blueprints deploy

After the deployment finishes, your Knowledge Bases and endpoints appear in the Context dashboard, where each endpoint's page shows the URL agents connect to.

If you need to make changes, update the blueprint file (sanity.blueprint.ts) and run the deploy command again.

Every deploy restores the blueprint's values, including settings changed in the dashboard or through the API, so make changes in the blueprint. sanity context update and sanity context delete refuse to change the title or description of a Knowledge Base a blueprint manages, or to delete it.

Sometimes you want to remove a deployed resource so it won't run anymore or affect any future usage quotas.

To remove resources created with a blueprint, you need to either:

• Remove the definition from the blueprint, and run the deploy command again.
• Destroy the blueprint with the destroy command.

The blueprints destroy command removes, or undeploys, the blueprint from Sanity's infrastructure. It does not remove your local files.

npx sanity blueprints destroy

pnpm dlx sanity blueprints destroy

yarn dlx sanity blueprints destroy

bunx sanity blueprints destroy

For Context, destroying a blueprint:

• Deletes its MCP endpoints. Agents connected through them lose access.
• Keeps its Knowledge Bases, because deleting one would throw away its built content. The blueprint stops managing them; delete them in the dashboard if you want them gone.

To remove an MCP endpoint, delete its definition from the blueprint and deploy again. The endpoint is deleted.

Deleting a Knowledge Base's definition from the blueprint, or changing its name, fails the deploy, so a Knowledge Base and its built content are never removed by accident. Decide first what should happen to it:

• To keep it and stop managing it, add lifecycle: {ownershipAction: {type: 'detach'}} and deploy. That deploy releases it from the blueprint; then delete its definition.
• To delete it with its built content, add lifecycle: {deletionPolicy: 'allow'} and deploy, then delete its definition and deploy again.

If a blueprint-managed endpoint or Knowledge Base is deleted in the dashboard or through the API, the next deploy creates it again: an endpoint with the same name and URL, a Knowledge Base new and empty. To get rid of it for good, remove it from the blueprint as described above.

When you run blueprints destroy, it's as if you never used blueprints init during setup. The only difference is you still have all the files in your directory. To use this blueprint again and redeploy it, you'll need to let Sanity know about it. You can do this by running init again:

npx sanity blueprints init

pnpm dlx sanity blueprints init

yarn dlx sanity blueprints init

bunx sanity blueprints init

This launches an editing interface that lets you reconfigure the blueprint, if needed, and it reconnects the blueprint to Sanity.

Endpoints come back with the same URLs when redeployed to the same organization with the same names. Knowledge Bases are created new and empty, unless you attach the existing ones by ID.