Migrate from the Context Studio plugin to the new Context app

Move an agent from the Context Studio plugin to the Context app: create an endpoint, mint a Context token, swap the URL, and update Insights.

Sanity Context now runs at the organization level: MCP endpoints are created in the Context app instead of a sanity.agentContext document in your dataset, and they support knowledge bases. The Context Studio plugin is deprecated. Your existing MCP URLs keep working but receive no further updates. Your knowledge bases and Insights conversation history are already in the Context app; endpoint configurations are the one thing you recreate.

This guide explains how to move an agent from a dataset-addressed MCP URL to an endpoint in the Context app.

Prerequisites:

• The Context app, enabled automatically for organizations that used the Context plugin. If you don't see it, enable it in Manage under your organization's Apps → Sanity Labs.
• An Administrator or Developer role in the organization
• To attach a dataset as a source: an administrator role on that dataset's project

• Open the Context app and select New MCP endpoint.
• Name the endpoint and attach the sources your agent needs: knowledge bases, or the dataset your old configuration served. Attaching a dataset requires an administrator role on its project; the attach is what authorizes the endpoint to serve that dataset's content.
• Save. The endpoint's URL appears on its detail page. This is a new organization-addressed URL, not your old dataset-addressed one.

Existing MCP configurations were not migrated. Every endpoint must be created anew in the Context app. The old URL keeps serving until you point your agent at the new one.

Project tokens don't work on Context endpoints. You need an organization API token with Context access, and one token covers every Context endpoint in your organization.

• Go to your organization's API tokens in Manage: https://www.sanity.io/organizations/<orgId>/api/tokens
• Select Add API token, name it, and under Organization permissions check Context.
• Choose Viewer. Reading over MCP needs no more; pick Editor only if the same token also manages knowledge bases through the API.
• Store the token where your agent reads its secrets.

A token without Context access is rejected when the agent connects, with an error naming the missing grant.

Replace the MCP URL and token in your agent's configuration with the endpoint URL and the new token. This is the cutover: the old URL keeps serving until you switch, and restoring it rolls you back.

If your agent records conversations to Insights, update the integration in the same deploy. The old integration writes to your dataset through an API that is no longer served, and fails silently.

Conversations are now recorded with sanityInsightsIntegration from @sanity/context/ai-sdk, attributed to your new endpoint by its URL:

import {streamText} from 'ai'
import {createMCPClient} from '@ai-sdk/mcp'
import {createClient} from '@sanity/client'
import {sanityInsightsIntegration} from '@sanity/context/ai-sdk'

const MCP_URL =
  'https://api.sanity.io/v2026-09-01/context/organizations/<organizationId>/mcp/<name>'

const mcp = await createMCPClient({
  transport: {
    type: 'http',
    url: MCP_URL,
    // Needs read access; keep server-side
    headers: {Authorization: `Bearer ${process.env.SANITY_API_TOKEN}`},
  },
})

const client = createClient({
  apiVersion: '2026-08-25',
  token: process.env.SANITY_API_TOKEN,
  context: {organizationId: '<organizationId>'},
})

const result = streamText({
  model,
  messages,
  tools: await mcp.tools(), // The agent's toolset, straight from the MCP
  experimental_telemetry: {
    isEnabled: true,
    integrations: [
      sanityInsightsIntegration({
        client,
        threadId, // Your chat's thread id, unique within the org
        mcpUrl: MCP_URL, // Attributes the conversation to the MCP above
      }),
    ],
  },
})

If your agent doesn't use the AI SDK, save conversations directly with client.context.conversations.save (@sanity/client v8.4 or later). Your existing conversation history is already in the Context app; new conversations continue the same Insights view.

After the cutover, remove the sanity.agentContext document and the Context plugin from your Studio config. Nothing reads them anymore.