@sonordev/site-kit/mcp: WebMCP & Model Context Protocol
Make a marketing site something an AI agent can use, not just read.
An agent that lands on a normal site can only scrape it. This module gives the site three machine-facing surfaces, all driven by one set of tool definitions:
| Surface | Who uses it | Entry point |
|---|---|---|
| Remote MCP endpoint (Streamable HTTP) | Off-browser agents: Claude, Cursor, any MCP client | createMcpHandler |
| Server card and experimental AI catalog | Crawlers and clients discovering the endpoint | createMcpServerCardHandler, createMcpAiCatalogHandler |
| In-page WebMCP | Browser-driving agents | <WebMcpTools>, declarativeToolForm |
One definition feeding all three is the point. The alternative, a tool list for the endpoint and a separate one for the page, drifts, and a stale tool definition is worse than none, because the agent believes it.
The fast way: the built-in Sonor tools (7.0)
npx sonor-setup mcp --inquiry-form contactThat writes everything below for you, with tools you don't have to write:
@sonordev/site-kit/mcp/sonor reads Sonor through the same fetchers the
site's pages use, so an agent gets what a visitor gets.
| Tool | What an agent gets |
|---|---|
get_business_profile | Who the business is, where it works, phone, email, address, hours |
list_services | Its services, with links |
search_faq | Its answered questions, to quote instead of guessing |
find_pages | The page that covers a topic |
list_articles, get_article | Its articles (articles: false drops them) |
get_reviews | Reviews verbatim, with who wrote them, and the rating |
list_offerings | Priced products, services, events (opt-in: offerings: { path, read }, see below); private prices are left out |
check_availability | Open appointment times, read only (opt-in: booking: { path }) |
get_inquiry_form, send_inquiry | An inquiry for a person (opt-in: inquiry: { form }) |
// lib/mcp.ts
import 'server-only'
import { sonorMcpServer } from '@sonordev/site-kit/mcp/sonor'
import { getAllArticles, getArticle } from '@sonordev/press-kit/articles/server'
export const mcpServer = sonorMcpServer({
businessName: 'Example Law',
articles: { path: '/news', readMany: getAllArticles, readOne: getArticle },
inquiry: { form: 'contact' }, // the form's "Agent inquiries" switch must be on in Sonor
tools: [/* the site's own tools, served beside these */],
})
// app/api/mcp/route.ts
import { createMcpHandler } from '@sonordev/site-kit/mcp'
import { reportToolCallsToSonor } from '@sonordev/site-kit/mcp/sonor'
import { mcpServer } from '@/lib/mcp'
export const { POST, GET, DELETE, OPTIONS } = createMcpHandler({
server: mcpServer,
baseUrl: process.env.NEXT_PUBLIC_SITE_URL,
onToolCall: reportToolCallsToSonor(),
})Articles use Press Kit readers (8.3). Install @sonordev/press-kit alongside
Site Kit 8.3 or newer and pass getAllArticles as readMany and getArticle as
readOne, as above. Both receive the configured sub-site, so site pages and
agent tools read the same publication. Custom CMS adapters can implement the
exported McpArticleReaders shape. Provide both readers together; a partial
pair fails with an actionable error. The tools return only published public
article data and approved photo snapshots, never private photo briefs or files.
The 8.x compatibility adapter remains when neither reader is supplied, so
existing servers keep working. It's loaded only if an article tool is called.
New npx sonor-setup mcp --articles /news scaffolds explicit Press Kit readers.
For a site without articles, use articles: false or --no-articles and no
Press Kit install is needed. Migrating packages doesn't publish or broadcast.
list_offerings needs a reader (8.0). The catalog it lists belongs to
commerce-kit, so you hand the tool commerce-kit's
fetcher instead of site-kit importing it:
// lib/mcp.ts
import 'server-only'
import { sonorMcpServer } from '@sonordev/site-kit/mcp/sonor'
import { getOfferingsResult } from '@sonordev/commerce-kit/commerce/server'
export const mcpServer = sonorMcpServer({
businessName: 'Example Studio',
offerings: { path: '/shop', read: getOfferingsResult },
})read is required and is getOfferingsResult from
@sonordev/commerce-kit/commerce/server, so the site needs commerce-kit installed
(npm install @sonordev/commerce-kit). When a request fails it tells the agent the
catalog is unavailable; the plain getOfferings from the same entry also works, but
it reads an outage as an empty catalog. The other tools, list_services included,
don't. path is where the offerings' pages live: each offering links to
<path>/<slug> on the site, and path defaults to /shop. An agent can narrow the
list with type (product, service or event), search it with query, and cap
it with limit (at most 20). The tool, how it ranks a query, and its rule that a
price the business keeps private is never shown all stay in site-kit.
read is typed McpOfferingsReader, and what it returns is a list of McpOfferings
(a name, type, slug, descriptions and a price), or { ok, data } around that list. Both
types are exported from @sonordev/site-kit/mcp/sonor. commerce-kit's fetchers satisfy
them as they are, so you only meet the types if you supply the catalog from somewhere
else: write a function that takes ({ apiUrl, apiKey, projectId }, { type, limit }) and
returns the offerings, and answer { ok: false, data: [] } when the request fails, so
the agent hears "unavailable" instead of "nothing for sale".
Without read, sonorMcpServer throws when the server is built, with a message that
names the fix. npx sonor-setup mcp --offerings /shop writes this wiring for a new
site, import included, and tells you to install commerce-kit. Before 8.0 the option
was offerings: { path }; see
Moving a site to site-kit 8.
send_inquiry has a person behind it. It refuses unless
person_confirmed is true (the person asked to be contacted and agreed to
share their details), files through Sonor's agent-inquiry door with the
agent's badge (<host> MCP send_inquiry via <assistant>) and
human_approved, and only for a form that opted in. It's left off the
in-page surface, where the person's browser has the site's own form.
Sonor sees who called. onToolCall hands createMcpHandler's record of
each call (tool, outcome, in-page or remote, the agent's own name or its
User-Agent) to reportToolCallsToSonor, which sends it after the response
with Next's after(). Never the arguments or the answer. Sonor's AI
Visibility tab lists the agents and tools, and Echo offers the fix when a
tool keeps failing.
Discovery. llms.txt gains an "Agent access" section pointing at the
endpoint and card (automatic in the build-time file once /api/mcp exists),
and SiteKitLayout llmsDiscovery={{ siteUrl, mcpServerCard: true }} adds an HTML
<link rel="service-desc"> to /.well-known/mcp-server-card, preserving Next's
resource preload headers. AiDiscoveryLinks from the layout entry works on its own too.
A custom MCP server is left alone
The built-in tools are opt-in, never automatic. A site that runs its own MCP server (its own tools, transport names or llms.txt section, like a re-site-kit site) is a custom implementation, and site-kit keeps its hands off:
| What | Built-in server | Custom server |
|---|---|---|
npx sonor-setup mcp | writes the wiring (skips files that exist) | writes nothing, not even missing files, and says what's opt-in (--force replaces it, knowingly) |
| llms.txt "Agent access" section | added at build | not added (writeLLMsTxtToPublic({ mcp: true }) opts in) |
| Tool-call reporting to Sonor | onToolCall: reportToolCallsToSonor() | the same line, if you want it; nothing without it |
HTML service-desc link | SiteKitLayout with llmsDiscovery.mcpServerCard: true | the same, opt-in |
| Mixing in built-in tools | n/a | tools: [...sonorMcpTools({ businessName, exclude }), ...yourTools] |
"Built-in" means the site's /api/mcp server comes from sonorMcpServer or
sonorMcpTools (checked in the route and lib/mcp* by detectMcpServer, exported from
@sonordev/site-kit/seo/llms); anything else serving
/api/mcp or a server card is custom. To force the llms.txt section either
way: writeLLMsTxtToPublic({ mcp: false | true }),
createSitemap({ llmsAgentAccess }), or sonor-register-sitemap --write-llms --no-agent-access / --agent-access. It's also never added to markdown
that already names a server card.
Route files need no segment config: POST and GET route handlers are dynamic
by default in Next 16, and Cache Components rejects dynamic, runtime and
revalidate exports. (The hand-written examples below predate that; drop
those lines on a site with Cache Components on.)
Quick start
1. Define the tools
// lib/mcp/server.ts
import { defineMcpTool, type McpServerDefinition } from '@sonordev/site-kit/mcp'
const getServices = defineMcpTool({
name: 'get_services',
title: 'Get service catalog',
description:
'List everything this company builds, with what each service is for and ' +
'what it typically costs. Call this first when asked what they do.',
inputSchema: {
type: 'object',
properties: {
category: { type: 'string', description: 'Optional category filter.' },
},
},
annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
handler: ({ category }) => SERVICES.filter((s) => !category || s.category === category),
})
export const mcpServer: McpServerDefinition = {
info: {
name: 'io.example/site', // reverse-DNS, EXACTLY one slash
version: '1.0.0', // concrete semver, no ranges
title: 'Example Co.',
description: 'Tools for exploring Example Co.’s services and requesting work.',
instructions: 'Start with get_services. Use request_quote only with consent.',
},
tools: [getServices],
}2. Mount the endpoint
// app/api/mcp/route.ts
import { createMcpHandler } from '@sonordev/site-kit/mcp'
import { mcpServer } from '@/lib/mcp/server'
export const { POST, GET, DELETE, OPTIONS } = createMcpHandler({
server: mcpServer,
baseUrl: process.env.NEXT_PUBLIC_SITE_URL,
})
export const dynamic = 'force-dynamic'3. Mount the card and optional experimental catalog
The ext-server-card discovery draft
is experimental. It recommends the card beside the endpoint at
<streamable-http-url>/server-card and a domain catalog at
/.well-known/ai-catalog.json. With the default endpoint, use
/api/mcp/server-card as the site's canonical card URL:
// app/api/mcp/server-card/route.ts
import { createMcpServerCardHandler, MCP_SERVER_CARD_MEDIA_TYPE } from '@sonordev/site-kit/mcp'
import { mcpServer } from '@/lib/mcp/server'
export const { GET, OPTIONS } = createMcpServerCardHandler({
info: mcpServer.info,
tools: mcpServer.tools,
baseUrl: 'https://example.com',
contentType: MCP_SERVER_CARD_MEDIA_TYPE, // application/mcp-server-card+json
})// app/.well-known/ai-catalog.json/route.ts
import { createMcpAiCatalogHandler } from '@sonordev/site-kit/mcp'
import { mcpServer } from '@/lib/mcp/server'
export const { GET, OPTIONS } = createMcpAiCatalogHandler({
info: mcpServer.info,
baseUrl: 'https://example.com',
serverCardPath: '/api/mcp/server-card',
})The catalog returns application/ai-catalog+json. Both handlers use explicit
configuration and stay statically renderable without reading request data.
Keep existing /.well-known/mcp-server-card and /.well-known/mcp.json
aliases for clients that already use them. The card handler's default remains
application/json; set the vendor content type explicitly on the new path.
4. Register in-page (optional, for browser agents)
// app/layout.tsx: a CHILDLESS SIBLING, never a wrapper
<SiteKitLayout>{children}</SiteKitLayout>
<WebMcpTools endpoint="/api/mcp" />Pass no tool list. The component checks for WebMCP support first and only then
fetches tools/list from the endpoint. In a supported browser it starts when
the component mounts, without waiting for window load, an idle period, or a
human interaction. A browser without WebMCP makes no discovery request and
receives no catalog. Handing it descriptors from a server component instead
would put the whole catalog in every page's RSC payload.
defer={true} preserves the optional load + idle activation. Ordinary parent
renders keep the current registration; unmounting aborts discovery, remote
calls, and registrations that support the registration signal. If passing
tools or localTools explicitly, keep their arrays stable until the tools
change.
5. Rate-limit the public endpoint (Netlify)
A public MCP endpoint is an open door for scripted callers, and Netlify can
only rate-limit a native function (declarative config.rateLimit), never a
Next.js route handler. @sonordev/site-kit/mcp/transport is the relay that
puts the endpoint behind one. Three files, plus MCP_TRANSPORT_SECRET
(openssl rand -hex 32) in every deploy context, Functions scope:
// netlify/functions/mcp.mjs: owns /api/mcp in production
import { createNetlifyMcpRelay } from '@sonordev/site-kit/mcp/transport'
export default createNetlifyMcpRelay()
// Literal, in THIS file: Netlify reads path and rateLimit statically,
// so they can't be imported or spread from a constant.
export const config = {
path: '/api/mcp',
rateLimit: { windowSize: 60, windowLimit: 60, aggregateBy: ['ip', 'domain'] },
}// app/api/mcp/route.ts: answers only relayed (signed) calls in production
import { createMcpHandler } from '@sonordev/site-kit/mcp'
import { protectMcpHandlers } from '@sonordev/site-kit/mcp/transport'
import { mcpServer } from '@/lib/mcp/server'
export const { POST, GET, DELETE, OPTIONS } = protectMcpHandlers(
createMcpHandler({ server: mcpServer, baseUrl: process.env.NEXT_PUBLIC_SITE_URL, allowedOrigins: '*' }),
)
export const dynamic = 'force-dynamic'
export const runtime = 'nodejs'// app/api/mcp-internal/route.ts: the relay's target, 403 unless signed
import { createMcpInternalRoute } from '@sonordev/site-kit/mcp/transport'
import * as mcp from '../mcp/route'
export const { POST, GET, DELETE, OPTIONS } = createMcpInternalRoute(mcp)
export const dynamic = 'force-dynamic'
export const runtime = 'nodejs'What the relay does, so you don't have to re-derive it:
- Signs each request with
HMAC-SHA256(MCP_TRANSPORT_SECRET, label)in a transport header, overwriting anything the client sent under that name. The routes verify it withtimingSafeEqual. - Relays to
https://<deploy-id>--<site>.netlify.app/api/mcp-internal, the permalink of the deploy that took the call. The base URL comes from the function'scontext, never from a request header. - Refuses POST bodies over 64 KB (413), uses
redirect: 'error'and a 55 s timeout (under Netlify's 60 s limit), and answers 502 when the upstream fails. - Stamps responses
Cache-Control: no-storeand sets the transport header tonetlify-rate-limited-v1, which a release check can assert to prove a call went through the rate limit. - 503 when
MCP_TRANSPORT_SECRETis unset. The/api/mcproute is only enforced whenNODE_ENV === 'production', sonext devanswers a local client directly./api/mcp-internalis enforced everywhere.
The header and label default to x-site-mcp-transport and
site-mcp-transport-v1. A site with names already live passes the same
{ header, label } to all three factories (for example
x-example-mcp-transport / example-mcp-transport-v1). This entry is Node
only and imports no server-only, so the plain-Node function can load it. It
isn't re-exported from @sonordev/site-kit/mcp, which stays runtime-neutral.
Design notes
The card doesn't list tools, on purpose
The card's discovery shape omits primitives: what a server exposes can
vary with auth state and configuration, so the authoritative list is whatever
tools/list returns at call time. A card that inlined tools would be a second
source of truth that goes stale silently.
We still publish a summary (name + description + read-only flag) under
_meta['io.sonor.site-kit/tools']. _meta is the spec's sanctioned extension
point and requires a reverse-DNS prefix, so the hint rides along without
pretending to be standard. That's useful for crawlers that index the card and
never connect.
Experimental discovery and compatibility paths
Site-kit keeps /.well-known/mcp-server-card and /.well-known/mcp.json
for compatibility with existing integrations. The experimental
ext-server-card draft adds domain discovery through
/.well-known/ai-catalog.json, which links to the recommended endpoint-local
card at /api/mcp/server-card. These draft conventions aren't a guarantee
that every agent discovers or uses them. Keep the endpoint and existing card
URLs working while adding the catalog.
Dual-era protocol support
dispatch() answers both protocol eras on one endpoint:
- Modern (
2026-07-28): stateless, per-request_metacarrying the protocol version, mirrored intoMCP-Protocol-Version.server/discoverreplaces the handshake. No sessions, no GET stream (both return405). - Legacy (
≤ 2025-11-25): theinitializehandshake, which is what most shipped clients and SDKs still speak.
Supporting only the current revision would be spec-correct and unusable today.
Header mirroring: mismatch is fatal, absence isn't
The modern revision mirrors method and params.name into Mcp-Method and
Mcp-Name so intermediaries can route without parsing bodies, and requires
servers to reject disagreements (-32020).
We always reject a mismatch; that's the real security property, stopping
a load balancer and the server from acting on different values. A merely
absent header is tolerated unless you set strictHeaders: true, because a
public marketing endpoint exists to be reachable and today's clients frequently
omit the mirrors.
Tool failures come back as results, not transport errors
A missing argument or a thrown handler returns a normal result with
isError: true. That text goes back to the model, which can read it and
retry correctly. A JSON-RPC error goes to the client harness and usually
surfaces as a dead end.
Handler results are emitted twice
Structured returns become both structuredContent (for agents that parse) and
pretty JSON inside a text block (for agents that only read content). Emitting
one or the other makes you invisible to a large slice of the ecosystem.
Discovery is lazy, and gated on support
<WebMcpTools> does nothing at all unless document.modelContext exists. That
gate comes before the tools/list fetch, so the cost for a human visitor is a
single property check: not a request, and not a byte of page weight.
In-page tools are proxied, not re-implemented
<WebMcpTools> registers thin wrappers that POST tools/call to this site's
own endpoint, so the in-page tool and the remote tool run the same server-side
handler. It also keeps SONOR_API_KEY out of the client bundle: registering
real handlers client-side would pull server code, and the key with it, into a
'use client' graph and a public chunk.
Tools that genuinely need live DOM state go in localTools and run in-page.
Registration is deferred
<WebMcpTools> waits for the page to go quiet (useDeferredActivation) before
touching document.modelContext. Agents poll or listen for toolchange, so a
few hundred milliseconds costs nothing, while a blocked LCP costs a lot.
Writing good tools
The description is the highest-leverage field in this module. It's the only
thing a model reads when deciding whether to call the tool.
- Verb-led
snake_casenames:get_services,request_site_audit. - Say when to call it, not just what it returns: "Call this first when asked what they do."
- Set
annotationshonestly.readOnlyHinton lookups;destructiveHinton anything creating a record. Good agents use these to decide what needs a human. - Never
toolautosubmita lead form. That's how an agent files fifty audit requests by accident. - Return the caveat with the data. A pricing tool should return the ranges and the fact that they're ranges; otherwise the model quotes a number as a commitment.
Testing an endpoint by hand
curl -s https://example.com/.well-known/mcp.json | jq
curl -s -X POST https://example.com/api/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'Mcp-Method: tools/list' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools[].name'