Concepts & Strategy8 min readยท

Does Your Product Need an MCP Server? MCP vs a Plain API for AI Agents

A support agent calls a tool someone generated from your REST spec. It gets back a wall of raw endpoint JSON, paraphrases it, and tells a customer the return window is 45 days when the policy says 30.

A support agent calls a tool someone generated from your REST spec. It gets back a wall of raw endpoint JSON, paraphrases it, and tells a customer the return window is 45 days when the policy says 30. Whether your product needs an MCP server depends on who your agents are. If agents you don't build yourself have to find your tools, read their schemas, and sign in without custom glue code, you need one. If one in-house agent calls a few known endpoints, a plain API is enough. In Sanity you get both from one Content Lake: the APIs your frontend already uses, plus a read-only Context MCP endpoint scoped by groqFilter.

There's real risk on both sides. Every agent client your customers or teams use (Claude, Cursor, an in-house SDK loop) either reads a standard tool menu or gets a hand-written one that drifts out of date. Wrap fifty endpoints badly and the model picks the wrong tool. Skip scoping and it reads drafts it should never see.

So the real question isn't MCP or API. It's which agents you serve, whether they read or act, and who controls what they see. This guide compares four options on those terms: a plain API with custom tools, OpenAPI-generated MCP servers, Contentful's MCP server, and Sanity Context.

What does an MCP server add over a plain API?

An MCP server adds four things a plain REST or GraphQL API doesn't standardize: tool discovery, machine-readable input schemas, a shared authorization flow, and portability across agent clients. The API still does the work underneath. MCP changes how an agent finds it and calls it.

Discovery comes first. A Model Context Protocol client sends a JSON-RPC tools/list request and gets back every tool the server exposes. Each tool has a name, a description, and an inputSchema (optionally an outputSchema too) that describes its arguments. A plain API has documentation written for people and maybe an OpenAPI file, but no protocol-level way for an agent to ask what it can do right now.

Authorization is the second gain. The 2025-06-18 MCP specification bases authorization on OAuth 2.1 with RFC 8414 server metadata, so a client can find out how to authenticate without a custom integration. With a plain API, every team that wires up an agent writes its own credential handling.

Portability is the third, and it usually decides the question. The same MCP server works in Claude Code, Cursor, VS Code, or an internal agent loop, and nobody has to re-declare tool definitions. With a plain API, every client team writes its own function-calling schemas by hand, and those copies drift as the API changes.

MCP doesn't add judgment. It won't decide which tools are worth exposing, what shape responses should take, or which records an agent may read. Those decisions are still yours, and they matter more than the choice of protocol.

Sanity Context shows the split clearly. The Content Lake keeps serving your website through its existing APIs, while Context MCP exposes the same content as a hosted, read-only endpoint. In GROQ mode, a tools/list call against it returns initial_context, schema_explorer, groq_query, and array_field_reader. Because schema_explorer reads your deployed Schema, the agent learns where fields live instead of guessing.

Illustration for Does Your Product Need an MCP Server? MCP vs a Plain API for AI Agents
Illustration for Does Your Product Need an MCP Server? MCP vs a Plain API for AI Agents

Why do thin MCP wrappers make AI agents worse?

Thin MCP wrappers make agents worse because they copy an API's shape, not its tasks, into the model's context window. Three failure modes show up most often: endpoint dumps, too many tools, and no scoping.

Endpoint dumps happen when a generator or a rushed developer turns every REST operation into a tool. The agent now has getEntry, listEntries, getAsset, and searchEntries, and each returns a raw payload. To answer a question about the return policy for boots, it chains three calls and paraphrases a pile of JSON. Paraphrasing is where facts drift. Tools that return schema-shaped objects the model can pass straight through work far better than tools that return a wall of text for the model to retell.

Too many tools is the second failure. In most tool-calling frameworks (the Vercel AI SDK, Anthropic's tool use, OpenAI's function calling), every tool schema and description is sent with each request. With ten focused tools, the model can keep the whole menu in view and pick correctly. With forty, it picks the wrong tool or calls the right one with the wrong arguments. OpenAPI generators handle this differently. Speakeasy creates one tool per operation by default, with filtering available. Stainless groups functionality into a few tools plus a docs-search tool.

No scoping is the third. A wrapper that inherits a broad API key lets the agent read drafts, internal notes, or another market's pricing. Also, every installed MCP server's tool descriptions go into the prompt as trusted text. A sloppy or malicious server can steer the agent before the user types anything, so read the source of any MCP server before you install it.

Sanity Context avoids the endpoint-dump pattern by design. Context MCP serves a small, fixed set of tools per mode rather than one tool per API route. groq_query returns results in the shape your Schema defines. If your agent needs even fewer tools, you filter them in the client.

One source type per endpoint, and no error if you mix them

A Context MCP endpoint serves one source type. If you attach a dataset source and Knowledge Base sources to the same endpoint, the dataset wins: the agent gets the GROQ tools, the Knowledge Bases are ignored, and nothing raises an error. Use separate endpoints, or override a single connection with ?mode=groq or ?mode=knowledge_base.

How should you scope and govern an MCP server for content?

Scope an MCP server for content at the endpoint, not in the prompt, and keep read and write access separate. Before an agent goes live, enterprise teams need to answer three questions: which records can it read, what instructions govern it, and which credentials does it carry?

Record-level scoping is where most homegrown servers are weakest. Filtering inside each tool's code works until someone adds a tool and forgets the filter. Context MCP sets the limit on the endpoint instead. groqFilter is an optional GROQ expression, up to 10,000 characters, that limits which documents the agent can read at all. The guidance is to use it to scope, not to shape: the filter decides what's visible, and queries decide ranking and which fields come back. The perspective setting defaults to published, so drafts stay hidden unless you choose drafts or raw.

Instructions are the second control. Each endpoint has an instructions field that holds up to 10,000 characters of plain-language guidance. Teams that keep the agent's system prompt as a document in the Studio can let editors adjust voice and scope without code changes. They can also stage those changes with Content Releases the same way they stage a website launch, with drafts, scheduling, history, and audit trails.

Credentials are the third. Context MCP requires an organization API token with Context Viewer permissions. A project token is refused with a 403 contextGrantRequired error, which keeps general-purpose project keys out of production agent traffic. For compliance reviews, Sanity provides SOC 2 Type II, GDPR compliance, regional hosting for data residency, and a published sub-processor list.

The line between reading and writing ties these controls together. Context MCP is read-only and can't write back to your dataset. When an agent does need to act, for example by patching documents or managing releases, that's a separate decision with separate credentials. The read/write Sanity MCP server covers it.

What does each MCP approach cost in maintenance and lock-in?

The cheapest approach to build is rarely the cheapest to run. A plain API with hand-written tools costs little on day one and more every time the API or the list of clients changes. A generated MCP server is the reverse: fast to set up, but costly in model confusion if the spec is large. A managed MCP server tied to where your content lives takes the least ongoing work, as long as its tools fit your tasks.

Hand-written tools carry a hidden multiplier. Each agent client re-declares schemas and auth, so three clients means three copies to update when a field is renamed. Nothing warns you that the copies have drifted until an agent fails in production.

OpenAPI generators from Speakeasy or Stainless keep tools in sync with the spec, which removes the drift problem. The cost moves to the number and shape of tools instead. One tool per operation on a large spec produces a menu the model struggles to choose from, so someone ends up curating filters and descriptions anyway.

Vendor MCP servers move the maintenance to the vendor. Contentful offers an official hosted remote server and a local open-source @contentful/mcp-server. Both cover entries, assets, content types, environments, and AI Actions. According to third-party MartechDB (October 2026), the hosted server has more than 80 tools and the local one more than 60. That broad, create-read-update-delete coverage suits authoring work. It's a large menu for a customer-facing agent that only needs to answer questions.

Lock-in needs a closer look. MCP itself reduces lock-in to any one client, because any compliant client can connect. Models matter too: Context MCP doesn't care which LLM you point at it. What's left is a dependency on where your content lives, and Sanity Context keeps that in one place. In GROQ mode the endpoint queries the Content Lake at request time, so there's no build step and nothing to keep in sync. With dataset embeddings turned on, semantic search runs over the same documents rather than through a separate vector pipeline you'd have to maintain.

How do you implement an MCP server that delivers CMS content as agent-ready tools?

To deliver content as agent-ready tools, structure it in a Schema the agent can read, expose a small set of task-shaped tools, scope access at the endpoint, and keep reads and writes on separate servers. In Sanity Context, that takes six steps.

1. Deploy your Schema with sanity schema deploy (Studio v5.1.0 or later). Without it, GROQ mode returns JSON-RPC error -32004.
2. Create a Context MCP endpoint at https://api.sanity.io/v2026-11-03/context/organizations/:organizationId/mcp/:mcpEndpointName and authenticate with an organization token that has Context Viewer permissions.
3. Set groqFilter to the documents the agent may read, write its instructions, and leave perspective set to published.
4. Pick the retrieval mode. GROQ mode suits structured, consistent content and stays exact across hundreds of thousands of records. Where the useful detail sits in prose fields, turn on dataset embeddings and use text::semanticSimilarity() inside score(), next to structured filters, in one query. Semantic search ranks results; it doesn't filter them.
5. Run tools/list to confirm what the endpoint exposes before you connect an agent loop.
6. For authoring agents, run npx sanity@latest mcp configure to connect the read/write server at https://mcp.sanity.io. It runs GROQ queries, manages releases, and patches documents, limited by its role and permissions.

This setup is why Sanity describes itself as the AI Content Operating System, the intelligent backend for companies building AI content operations at scale. Legacy platforms add AI on the side of the content. Sanity is built for it, so the website API, the production agent endpoint, and the authoring agent all read one Content Lake. For PDFs, websites, and help centers, Knowledge Bases (currently in beta) build an outline and search index that Context MCP serves in Knowledge Base mode.

โœจ

Two MCP servers, one Content Lake

Context MCP is the hosted, read-only endpoint for production agents, and it can't write back to your dataset. The Sanity MCP server at mcp.sanity.io is read/write and serves authoring agents in Claude Code, Cursor, VS Code, OpenCode, v0, Lovable, and Replit. Both work from the same Content Lake and Schema, so you don't have to choose between them.

Does your product need an MCP server? A decision framework

Your product needs an MCP server if agents outside your own codebase will use it. It probably doesn't if a single internal agent calls a handful of known endpoints. Three questions settle most cases: who will use your tools, whether they only read or also act, and how much governance and maintenance you can keep up.

Start with who will use them. If only your own backend agent calls your API and one team owns both sides, hand-written function-calling tools are fine and give you full control. Once customers, partners, or other internal teams want to connect from Claude, Cursor, or their own agent loops, a standard tools/list menu and a shared auth flow mean none of them has to rebuild your integration.

Next, decide between reads and actions. Read tools query content, look up product information, and fetch state. Write tools change state, and the agent acts as the user, which requires the user's credentials and an audit trail. Composite tools wrap a workflow, so one tool call maps to several backend calls. Many products only need reads for their first agent. Keep that server read-only, and add writes later as a separate server with its own deliberately granted credentials.

Then look at governance and maintenance. Ask who decides what the agent can see, who edits its instructions, and who updates the tools when the Schema changes. If the answer is an engineer, by redeploying, expect that queue to grow with every new agent.

For content, the answer usually comes out the same way. Customer-facing answers need a read-only, scoped endpoint that returns structured responses. Editorial automation needs a server that can write, with auth limited by role. Sanity Context covers the first with Context MCP, groqFilter, and instructions governed in the Studio. mcp.sanity.io covers the second, and both read the same Content Lake. If your agents don't need discovery or cross-client use yet, keep the plain API and revisit the question when a second agent client shows up.

MCP vs a plain API: how content options for AI agents compare

FeatureSanityPlain API + custom toolsOpenAPI-generated MCP (Speakeasy/Stainless)Contentful MCP server
Tool discovery across agent clientsStandard tools/list on Context MCP returns initial_context, schema_explorer, groq_query, and array_field_reader. mcp.sanity.io works in Claude Code, Cursor, VS Code, and more.No standard discovery. Each client (Claude, Cursor, an in-house SDK loop) re-declares tool schemas by hand, so definitions drift between teams.Tools are generated from your OpenAPI spec and exposed through tools/list, so any MCP client can discover them. Tool quality depends on how the spec is shaped.An official hosted remote server plus the open-source @contentful/mcp-server, both discoverable by MCP clients. Requires the Contentful MCP app installed per space or environment.
Tool shape and countFour task-shaped tools in GROQ mode and three in Knowledge Base mode (beta). Responses are schema-shaped objects the model can pass straight through.Whatever you write. You fully control shape and count, but every task-level tool is custom code your team owns, documents, and updates.Speakeasy defaults to one tool per API operation (filterable); Stainless groups operations into a few tools plus docs search. Tools tend to mirror endpoints, not tasks.Broad create-read-update-delete coverage of entries, assets, content types, environments, and AI Actions. MartechDB (Oct 2026) counts 80+ hosted and 60+ local tools, a large menu for one agent.
Separation of read and write accessContext MCP is read-only and can't write back to the dataset. Authoring agents use the separate read/write mcp.sanity.io, limited to its role and permissions.Possible if you split read and write tools and credentials yourself. Nothing in the API enforces that split for agent traffic.Inherits whatever the spec exposes. Write operations appear next to reads unless you filter them out at generation time or in the client.Read and write tools ship together, which suits authoring. Limiting an agent to reads depends on the token and permissions you configure.
Limiting which records an agent can readNative groqFilter (up to 10,000 chars) limits which documents the endpoint serves. Perspective defaults to published, so drafts stay hidden unless you opt in.Scoping lives in your API middleware or tool code. It works, but it's per-tool logic that has to be re-checked each time someone adds a tool.Limited by the API key and the operations you include. Document-level filtering for agents requires changes to the underlying API.Limited by space, environment, and the permissions on the token you issue. Narrower per-agent subsets of content are set up through those permissions.
Search and retrieval inside the toolGROQ mode with dataset embeddings uses text::semanticSimilarity() inside score(), blended with structured filters in one query. Semantic search ranks; filters still filter.You build search yourself, often with a separate vector database kept in sync with the content by a pipeline you maintain.Only as good as the API's existing search endpoints. Stainless adds a docs-search tool; semantic retrieval over your content has to exist in the API first.Tools query entries through Contentful's APIs. Semantic or hybrid retrieval typically comes from an external search service connected through the App Framework.
Control over agent instructionsThe endpoint's instructions field holds up to 10,000 chars. System prompts can live as documents that editors adjust in the Studio and stage with Content Releases.Instructions live in application code or config. Changing the agent's voice or scope means a code change and a deploy.Tool descriptions come from the spec. Agent-level instructions sit in whichever client or framework runs the agent.Agent instructions are set in the client or framework that connects to the server. Prompt text can be stored as entries, with the wiring left to your own code.