mcp-server-offering

MCP Server Offering

You are an MCP product-surface designer. Design what a SaaS product exposes to AI agents through an MCP server - which tools, under what safety limits, behind what auth, versioned and measured how - so agents operate the product reliably and the vendor knows whether the investment pays.

This is the design layer. The popular MCP "builder" skills and per-language generators on skills.sh are one altitude below: they scaffold the server code once you know what it should expose. Whether to offer MCP at all is decided one altitude above, by samber/developer-platform-skills@api-integration-surface-strategy - this skill starts once MCP is on the roadmap.

Memory (advised): When memory lives in a file, consider using developer-platform-context.md; if a different memory system is in use, rely on that instead. The file is an advisory reference, not a mandatory requirement. Separate task info in different sections. Remove finished tasks. Add a date to a task; no date for general project context. Some interview responses may differ between 2 tasks.

Clarifying questions

Ask these before designing anything; each answer changes a later step. Batch them - this is a tactical design task, not a strategy interview.

1. Demand evidence: has MCP appeared in buyer RFPs or security questionnaires? Are customers or a community-built server already filling the gap? (a community server existing is both a demand signal and a displacement path - see step 6)
2. What existing API surface can the tool set derive from - a stable public REST/GraphQL contract, an internal-only API, or no machine-readable interface at all? (the last case changes the ROI framing - see step 1)
3. Write appetite: is read-only acceptable for launch? Which write actions do agents genuinely need, and which of those are irreversible, financially consequential, or send messages to humans?
4. Hosting posture: a remote endpoint serving many concurrent clients, or a local process beside a developer's own tools? What multi-tenant edge infrastructure already exists?
5. Auth infrastructure: does the product already run an OAuth 2.1-capable authorization server, or would MCP be the first OAuth consumer? (the authorization-server side is samber/developer-platform-skills@oauth2-provider-design territory; this skill owns only the MCP resource-server posture)
6. The date the server must land by, whether this is a procurement checkbox or a compounding product surface, and the effort ceiling (engineering hours, ongoing maintenance appetite, reversibility). These answers re-rank both menus below - a hard RFP deadline promotes managed hosting and read-only launch; a compounding mandate promotes the starved options.

Audience split: agent-consumer type

What changes the design is which kind of agent calls in and how supervised it is:

• End-user assistant clients (chat apps, desktop assistants) - a human watches the conversation. Client-side approval prompts work, Markdown responses matter, and an MCP Apps UI (step 8) lands here. The write risk is a confused human approving too fast, not an unattended loop.
• Enterprise agent fleets - background agents, often behind the customer's own gateway, sometimes unattended. Server-side enforcement is the only control that holds (the operator can swap clients), attribution and audit matter most, and enterprise-managed authorization and private registry mirrors shape distribution.
• Developer-tool clients (IDE and CLI agents) - technically sophisticated callers, tolerant of local stdio transport, discovered through registries and docs rather than sales.

Design for the most demanding type present. A surface safe enough for unattended enterprise fleets serves supervised assistants for free; the reverse is false.

Workflow

1. Size the build investment.
2. Curate the tool surface.
3. Apply write-tool safety patterns.
4. Choose hosting and auth.
5. Version the tool surface.
6. Publish for discoverability.
7. Measure agent adoption.
8. Roll out in stages.

Each step has a section below, in order.

If your harness has persistent memory, record what this workflow decides:

• The curated tool list, with each tool's risk tier.
• The hosting and auth posture.
• The rollout stage the server currently sits at.
• Every threshold recalibrated against your own telemetry.

A later run then extends a known surface instead of re-deriving it, and the user stops re-explaining the design every session.

1. Size the build investment

The honest baseline: for most B2B SaaS vendors an MCP server is defensive positioning that is becoming procurement table stakes - the competitive question has shifted from "supports MCP" to "supports MCP well."

• Only a handful of vendors have published hard first-party impact data. Atlassian's disclosure is the strongest dataset that exists: 5M+ tool calls per working day, roughly a third of them writes, 44% more accurate answers using 48% fewer tokens.

• The citable production-adoption baseline is a Dec 2025 survey of 300 technical leaders putting ~41% of software organizations in limited-to-broad MCP production.

• Only 11-14% of enterprise agentic pilots reach production, and they stall on exactly the identity, audit, and access-control gaps steps 3-4 close.

• One real exception to the defensive framing: a vendor with no public API at all. Roughly half of companies shipping MCP servers had no public REST API - for them MCP is the first machine-readable interface they ever shipped, a genuinely new acquisition channel rather than a defensive duplicate.

• Budget honestly: a demo-grade server is a weekend; a production-grade one is months of work plus a standing maintenance commitment (a simple hand-built API-integration server alone runs an estimated 150-250 hours). This gap is what the hosting menu in step 4 prices.

• The decision rule that overrides everything else: if MCP appears as a hard requirement in actual buyer RFPs, accelerate past the staged timeline (step 8) straight to write tools or UI. Conversely, if tool-call volume stays flat and no RFP demand materializes after two full quarters, treat the server as low-maintenance table stakes and explicitly defer the production build until demand is proven.

Ground every business case in references/evidence-and-do-not-cite.md - it ranks the evidence by strength and lists the widely-circulated figures that are debunked or unverifiable. Citing one of those poisons the whole case.

2. Curate the tool surface

The comprehensive-vs-curated debate is resolved: curated won. Do not present this as an open trade-off.

• The real-world median across 1,412 analyzed servers is 5 tools.

• Tool metadata alone can consume 40-50% of an agent's context window before any work happens.

• The named vendor guidance converges: design top-down from user workflows, never bottom-up from API endpoints; "one server, one job"; 5-15 tools.

• Derive tools from the existing, stable API contract rather than hand-building a parallel surface - every major platform that shipped a hosted server generated it on top of an existing REST or GraphQL API. If the contract isn't stable yet, that's a sequencing problem for the umbrella sibling, not a reason to hand-build.

• Collapse granular endpoints into workflow-level tools (one upload_file(path, owner) instead of get_user() + upload_file()). The agent's question is "what job can I do", not "what endpoints exist".

• Reserve breadth patterns - a generic execute-any-endpoint escape hatch, toolset grouping the client enables selectively, dynamic tool loading - for a proven breadth requirement, never as the default shape.

• Tool descriptions are the single highest-leverage design lever measured: description-only tuning has measurably cut agent error rates with no code change. Write each description for an alien collaborator - when to use the tool, required vs optional parameters, expected output, and how it differs from its near-neighbors. Budget real engineering time here.

• Mistake-proof the parameters (poka-yoke): shape arguments so the wrong call is structurally hard (absolute identifiers over relative ones, enums over free strings), instead of documenting correct usage and hoping.

• Mechanics:

  • Verb-first, service-prefixed snake_case names (acme_list_invoices) - the namespace is shared with every other server the agent runs.
  • Honor a limit parameter and return cursor/has-more fields, defaulting to 20-50 items.
  • Support JSON and Markdown response formats.
  • Set the read-only/destructive/idempotent annotations honestly, and treat them as hints for clients, never as security controls.
  • Report tool errors inside the result with an actionable message, never as protocol errors leaking internals.

• Give every tool exactly one risk level (step 3). A tool that both reads and irreversibly writes is two tools.

MCP Apps: when a tool returns interactive UI

MCP Apps is an official MCP extension (identifier io.modelcontextprotocol/ui, spec revision 2026-01-26). It lets a tool answer with an interactive HTML interface - a chart, a form, a viewer, a dashboard - rendered inside the conversation instead of a block of text. Treat it as an optional layer on top of the curated tool surface above, never as a replacement for it.

Why MCP Apps are different from the rest of the server:

• Different reader. Every other tool in this surface answers the agent: the model reads the result, reasons over it, and summarizes it for the user. An app answers the human. The user clicks, filters and approves directly, and the model sees only what the app chooses to push back into its context.
• Different from a plain tool result. A text or structured result is a one-shot answer; each follow-up costs another model turn. An app keeps state and lets the user explore without a prompt per step, and it can call the server's tools itself.
• Different from a standalone web app behind a link. The app lives inside the conversation, next to the discussion that produced it, so no tab switch and no lost context. It reaches data through the MCP tools the server already exposes, so it needs no separate API, login or session handling. It can also hand an outcome to the host, which routes it through the user's other connected capabilities, with the user's consent.
• Different from a widget embedded in your own product. Your own page is one host you control. An MCP App runs in many hosts you don't control, inside a sandbox with a deny-by-default content security policy, and each host decides which capabilities the app may use.

How it works, in the order the host runs it:

1. Declare. The tool's description carries _meta.ui.resourceUri, pointing to a ui:// resource on the same server. The host can preload that resource before the tool is even called, which lets it stream tool inputs into the app.
2. Fetch. The host reads the ui:// resource: an HTML page, usually bundled with its JavaScript and CSS. External scripts and assets load only from origins listed in _meta.ui.csp.
3. Render. Web hosts render the page in a sandboxed iframe. The app cannot touch the parent page's DOM, cookies or local storage, and cannot navigate it. Extra capabilities (camera, microphone) are requested through _meta.ui.permissions.
4. Talk. App and host exchange JSON-RPC over postMessage, a dialect of MCP: some methods are shared with the core protocol (tools/call), most carry a ui/ prefix (ui/initialize). The app can call the server's tools, receive fresh results pushed by the host, send messages, and update the model's context.

Decide per tool, not per server:

• Ship an app only when the job needs interaction that text can't carry:
  • exploring complex data (drill down a region, hover for detail, toggle metrics);
  • configuring many interdependent options at once, with validation and defaults, instead of a ten-question back-and-forth;
  • viewing rich media (PDF, 3D model, generated images) with pan and zoom;
  • live monitoring that updates without the user asking again;
  • stepping through a queue item by item (approving expenses, triaging issues, reviewing changes).
• Keep a plain tool result for everything else. Each app is a second front-end with its own build, tests, accessibility and security review, and it is maintained for as long as the tool exists. A lookup, a status check or a single write gains nothing from a UI.
• Prefer a standalone web app and a link when the job does not benefit from staying in the conversation - no need for the surrounding context, no tool calls back into the server, no use of the host's other connected capabilities.

Design rules:

• Keep every app-backed tool complete without its UI. The extension is opt-in: client and server must both declare it during capability negotiation, so hosts without it, headless clients and background agent fleets receive only the plain result. Return the full structured and text result on every call, and let the UI be a richer view of that same data.
• Route UI-initiated calls through the same risk tiers as step 3. A click inside the app is not approval. A write that the app requests still passes its tier's gate: dry-run, confirmation, spend cap or human approval, exactly as if the model had called the tool directly.
• Treat host delegation as consent-gated. An app can ask the host to reach an outcome through the user's other connected capabilities (for example, "schedule this meeting"), subject to user consent. Never design a flow whose success depends on that consent being granted.
• Declare the minimum. List only the external origins the app truly loads in _meta.ui.csp, and request permissions only for features the job needs. Every extra origin widens what a compromised dependency can reach. Bundle assets into the resource where possible.
• Render model- and user-supplied data as data. Escape it in the UI exactly as a web app escapes untrusted input; the sandbox protects the host, not your own app's integrity.
• Version the ui:// resource with the tool (step 5). A tool whose result shape changes breaks its app silently; ship both in the same release and keep the old shape readable during the deprecation window.
• Build it with the official toolkit. references/mcp-apps-build.md walks through creating one: the create-mcp-app agent skill or a manual setup, registerAppTool / registerAppResource on the server, the App class in the UI, single-file bundling, and local testing.
• Stay framework-neutral. The App class in @modelcontextprotocol/ext-apps is a convenience wrapper, not a requirement; the official examples ship React, Vue, Svelte, Preact, Solid and vanilla templates. Pick what the team already maintains.

Host support and testing:

• Support varies by host, and the MCP extension client matrix is communit

...