Skip to content

Commit 399bde5

Browse files
localdenlocalden
committed
Add Security docs section, SEO improvements, and doc site enhancements
- Add Authorization guide covering per-server and per-tool OAuth patterns - Add CSP & CORS guide extracted from Patterns doc - Group both under a new Security section in the documentation nav - Replace CSP & CORS section in Patterns with cross-reference to new guide - Rename doc site title from package name to 'MCP Apps' - Rename 'Modules' nav section to 'API Documentation' - Ensure Security section appears before API Documentation in TOC - Add SEO plugin with JSON-LD structured data (TechArticle/WebPage) - Add per-page meta descriptions from frontmatter - Add description frontmatter to all documentation pages - Add hostedBaseUrl for sitemap.xml generation and canonical URLs - Normalize document page slugs to lowercase hyphenated format - Update compressed navigation and search index data to match new slugs
1 parent 30f79b9 commit 399bde5

10 files changed

Lines changed: 579 additions & 57 deletions

‎docs/agent-skills.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
title: Agent Skills
3+
description: Use Agent Skills to build, migrate, and extend MCP Apps with AI coding agents. Install skills that scaffold new apps, convert OpenAI Apps, and add UI to existing servers.
34
---
45

56
# Agent Skills

‎docs/authorization.md‎

Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
1+
---
2+
title: Authorization
3+
group: Security
4+
description: Learn how to protect MCP App tools with OAuth authorization, including per-server and per-tool auth patterns, token verification, and UI-initiated auth escalation.
5+
---
6+
7+
# Authorization
8+
9+
MCP Apps can protect tools behind OAuth authorization. There are two approaches:
10+
11+
- **Per-server authorization** — The entire MCP server requires authentication at connection time. Every request must include a valid token, regardless of which tool is being called. This is the simpler model when all tools are sensitive.
12+
- **Per-tool authorization** — Only specific tools require authentication. Public tools work without a token, and the OAuth flow is triggered only when the user calls a protected tool. This lets you mix public and protected tools in the same server.
13+
14+
Both approaches use the same underlying mechanism: HTTP `401` responses with [Protected Resource Metadata](https://modelcontextprotocol.io/specification/latest/basic/authorization#authorization-server-location). The difference is _when_ the `401` is returned — on every unauthenticated request, or only when a protected tool is called.
15+
16+
For the full protocol specification — including OAuth 2.1 requirements, discovery mechanisms, client registration approaches, token handling, and security considerations — see the [MCP Authorization specification](https://modelcontextprotocol.io/specification/latest/basic/authorization).
17+
18+
## Shared setup
19+
20+
Regardless of which approach you choose, you need OAuth discovery metadata and token verification. These are the same for both.
21+
22+
### OAuth discovery metadata
23+
24+
The MCP specification requires servers to implement [authorization server discovery](https://modelcontextprotocol.io/specification/latest/basic/authorization#authorization-server-discovery) so clients know how to authenticate. Two well-known endpoints are needed:
25+
26+
**Protected Resource Metadata** (`/.well-known/oauth-protected-resource`) — tells clients where to find the Authorization Server. The MCP SDK's `mcpAuthRouter` handles this automatically.
27+
28+
**Authorization Server Metadata** (`/.well-known/oauth-authorization-server`) — advertises the authorization and token endpoints, supported scopes, and whether [Client ID Metadata Documents](https://modelcontextprotocol.io/specification/latest/basic/authorization#client-id-metadata-documents) (CIMD) is supported:
29+
30+
```ts
31+
app.get("/.well-known/oauth-authorization-server", (_req, res) => {
32+
res.json({
33+
...oauthMetadata,
34+
client_id_metadata_document_supported: true,
35+
});
36+
});
37+
```
38+
39+
Setting `client_id_metadata_document_supported: true` tells MCP clients to use CIMD instead of [Dynamic Client Registration](https://modelcontextprotocol.io/specification/latest/basic/authorization#dynamic-client-registration) (DCR). With CIMD, the `client_id` is a URL that serves the client's metadata document, removing the need for a registration endpoint. See [Client Registration Approaches](https://modelcontextprotocol.io/specification/latest/basic/authorization#client-registration-approaches) in the spec for the full list of options and priority order.
40+
41+
### Token verification
42+
43+
Verify access tokens as JWTs against the identity provider's JWKS endpoint. The `jose` library handles key fetching and caching:
44+
45+
```ts
46+
import { createRemoteJWKSet, jwtVerify } from "jose";
47+
48+
const JWKS = createRemoteJWKSet(new URL(`${IDP_DOMAIN}/.well-known/jwks.json`));
49+
50+
const { payload } = await jwtVerify(token, JWKS, {
51+
issuer: IDP_DOMAIN,
52+
});
53+
```
54+
55+
MCP servers must validate that tokens were issued specifically for them — see [Token Handling](https://modelcontextprotocol.io/specification/latest/basic/authorization#token-handling) and [Access Token Privilege Restriction](https://modelcontextprotocol.io/specification/latest/basic/authorization#access-token-privilege-restriction) in the spec for the full requirements.
56+
57+
## Per-server authorization
58+
59+
With per-server authorization, every request to the `/mcp` endpoint must include a valid Bearer token. Any unauthenticated request receives HTTP `401`, and the host must complete the OAuth flow before the client can use any tools. This is the right choice when all tools are sensitive and there's no value in allowing unauthenticated access.
60+
61+
The TypeScript MCP SDK supports this out of the box via `mcpAuthRouter` and `ProxyOAuthServerProvider` — no custom HTTP handler logic is needed. See the [MCP SDK documentation](https://github.com/modelcontextprotocol/typescript-sdk) for setup details.
62+
63+
## Per-tool authorization
64+
65+
With per-tool authorization, the `/mcp` endpoint handler inspects the raw JSON-RPC request body, checks whether any message targets a protected tool, and only enforces authentication for those calls. Public tools pass through without a token.
66+
67+
### How it works
68+
69+
1. The server maintains a set of tool names that require authorization
70+
2. When a JSON-RPC request arrives at the `/mcp` endpoint, the server inspects the request body to determine if any message is a `tools/call` targeting a protected tool
71+
3. If a protected tool is being called and no valid Bearer token is present, the server returns HTTP `401` with a [`WWW-Authenticate` header](https://modelcontextprotocol.io/specification/latest/basic/authorization#protected-resource-metadata-discovery-requirements) pointing to its [Protected Resource Metadata](https://datatracker.ietf.org/doc/html/rfc9728)
72+
4. The MCP host (e.g., Claude Desktop) sees the `401`, discovers the authorization server via the metadata URL, runs the [OAuth flow](https://modelcontextprotocol.io/specification/latest/basic/authorization#authorization-flow-steps) with the user, and retries the request with the acquired token
73+
5. On retry, the server verifies the token, extracts the user identity, and creates a per-request MCP server instance with that auth context
74+
6. Unprotected tools pass through without any token check — they work for everyone
75+
76+
This design means authorization is enforced at the HTTP boundary (as [required by the spec](https://modelcontextprotocol.io/specification/latest/basic/authorization#access-token-usage)), not as a tool-level error. The MCP server itself never sees unauthorized requests for protected tools.
77+
78+
### Enforcing HTTP 401
79+
80+
The [MCP auth specification](https://modelcontextprotocol.io/specification/latest/basic/authorization#access-token-usage) requires protected resources to return HTTP `401` responses — not tool-level errors.
81+
82+
Start by defining which tools require authorization. Then, in the `/mcp` endpoint handler, inspect the raw JSON-RPC request body, check whether any message targets a protected tool, and either verify the Bearer token or return `401` before the request ever reaches the MCP server:
83+
84+
```ts
85+
/** Tools that require a valid Bearer token — checked at the HTTP level for proper 401. */
86+
const PROTECTED_TOOLS = new Set(["get_account_balance", "manage_branch_admin"]);
87+
88+
app.all("/mcp", async (req, res) => {
89+
// Parse the JSON-RPC body — it may be a single message or a batch
90+
const messages = Array.isArray(req.body) ? req.body : [req.body];
91+
92+
// Check if any message is a tools/call for a protected tool
93+
const needsAuth = messages.some(
94+
(msg: any) =>
95+
msg?.method === "tools/call" && PROTECTED_TOOLS.has(msg.params?.name),
96+
);
97+
98+
// Extract and verify the Bearer token
99+
let authInfo: AuthInfo | undefined;
100+
const authHeader = req.headers.authorization;
101+
102+
if (authHeader?.startsWith("Bearer ")) {
103+
try {
104+
const token = authHeader.slice(7);
105+
const { payload } = await jwtVerify(token, JWKS, {
106+
issuer: IDP_DOMAIN,
107+
});
108+
authInfo = { token, sub: payload.sub as string };
109+
} catch {
110+
if (needsAuth) {
111+
return res
112+
.status(401)
113+
.set(
114+
"WWW-Authenticate",
115+
`Bearer resource_metadata="${resourceMetadataUrl}"`,
116+
)
117+
.json({
118+
error: "invalid_token",
119+
error_description: "The access token is invalid",
120+
});
121+
}
122+
}
123+
} else if (needsAuth) {
124+
return res
125+
.status(401)
126+
.set(
127+
"WWW-Authenticate",
128+
`Bearer resource_metadata="${resourceMetadataUrl}"`,
129+
)
130+
.json({
131+
error: "invalid_token",
132+
error_description: "Authorization required",
133+
});
134+
}
135+
136+
// Create a per-request MCP server with the auth context.
137+
// authInfo is undefined for public tool calls, populated for
138+
// authenticated requests — tool handlers use it to scope data
139+
// to the authenticated user.
140+
const server = createServer(authInfo);
141+
// ... handle the request with transport
142+
});
143+
```
144+
145+
The `WWW-Authenticate` header includes the [Protected Resource Metadata](https://modelcontextprotocol.io/specification/latest/basic/authorization#authorization-server-location) URL, which tells the client where to discover the authorization server.
146+
147+
### Defence-in-depth in tool handlers
148+
149+
Even though the HTTP layer enforces authorization, protected tool handlers should also verify `authInfo` as a defence-in-depth measure. If the HTTP layer is misconfigured or bypassed, the tool handler catches it:
150+
151+
```ts
152+
registerAppTool(
153+
server,
154+
"get_account_balance",
155+
{
156+
description: "Get account balance",
157+
inputSchema: { accountId: z.string() },
158+
},
159+
async ({ accountId }) => {
160+
if (!authInfo) {
161+
return {
162+
isError: true,
163+
content: [
164+
{
165+
type: "text",
166+
text: "Authentication required to access account data.",
167+
},
168+
],
169+
};
170+
}
171+
172+
const balance = await getBalance(authInfo.sub, accountId);
173+
return {
174+
content: [{ type: "text", text: `Balance: ${balance}` }],
175+
};
176+
},
177+
);
178+
```
179+
180+
### UI-initiated auth escalation
181+
182+
A powerful pattern is mixing public and protected tools in the same app. The app loads with public data (no auth required), and authentication is triggered only when the user performs a protected action. This is a practical application of the [step-up authorization flow](https://modelcontextprotocol.io/specification/latest/basic/authorization#step-up-authorization-flow) described in the spec:
183+
184+
1. A public tool (e.g., `manage_branch`) loads the UI with unauthenticated data
185+
2. The user clicks a button that calls a protected tool via `app.callServerTool()`
186+
3. The MCP host receives HTTP `401` and automatically runs the OAuth flow
187+
4. After the user authenticates, the host retries the tool call with the new token
188+
5. The protected data appears in the UI
189+
190+
```tsx
191+
function BranchItem({ branch }: { branch: Branch }) {
192+
const [adminData, setAdminData] = useState(null);
193+
194+
async function handleManage() {
195+
// This call may trigger the OAuth flow if the user
196+
// hasn't authenticated yet — the host handles it
197+
// transparently.
198+
const result = await app.callServerTool({
199+
name: "manage_branch_admin",
200+
arguments: { branch_id: branch.id },
201+
});
202+
setAdminData(result.structuredContent);
203+
}
204+
205+
return (
206+
<div>
207+
<span>{branch.name}</span>
208+
<button onClick={handleManage}>Manage</button>
209+
{adminData && <AdminPanel data={adminData} />}
210+
</div>
211+
);
212+
}
213+
```
214+
215+
This pattern keeps the initial experience fast (no login wall) while securing sensitive operations behind authentication. The host manages the entire OAuth flow — the app code simply calls the tool and handles the result.

‎docs/csp-cors.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
title: CSP and CORS
3+
group: Security
4+
description: Configure Content Security Policy and CORS for MCP Apps that make network requests from sandboxed iframes, including connectDomains, resourceDomains, and stable origin setup.
5+
---
6+
7+
# CSP & CORS
8+
9+
Unlike regular web apps, MCP Apps HTML is served as an MCP resource and runs in a sandboxed iframe with no same-origin server. Any app that makes network requests must configure Content Security Policy (CSP) and possibly CORS.
10+
11+
**CSP** controls what the _browser_ allows. You must declare _all_ origins in {@link types!McpUiResourceMeta.csp `_meta.ui.csp`} ({@link types!McpUiResourceCsp `McpUiResourceCsp`}) — including `localhost` during development. Declare `connectDomains` for fetch/XHR/WebSocket requests and `resourceDomains` for scripts, stylesheets, images, and fonts.
12+
13+
**CORS** controls what the _API server_ allows. Public APIs that respond with `Access-Control-Allow-Origin: *` or use API key authentication work without CORS configuration. For APIs that allowlist specific origins, use {@link types!McpUiResourceMeta.domain `_meta.ui.domain`} to give the app a stable origin that the API server can allowlist. The format is host-specific, so check each host's documentation for its supported format.
14+
15+
<!-- prettier-ignore -->
16+
```ts source="../src/server/index.examples.ts#registerAppResource_withDomain"
17+
// Computes a stable origin from an MCP server URL for hosting in Claude.
18+
function computeAppDomainForClaude(mcpServerUrl: string): string {
19+
const hash = crypto
20+
.createHash("sha256")
21+
.update(mcpServerUrl)
22+
.digest("hex")
23+
.slice(0, 32);
24+
return `${hash}.claudemcpcontent.com`;
25+
}
26+
27+
const APP_DOMAIN = computeAppDomainForClaude("https://example.com/mcp");
28+
29+
registerAppResource(
30+
server,
31+
"Company Dashboard",
32+
"ui://dashboard/view.html",
33+
{
34+
description: "Internal dashboard with company data",
35+
},
36+
async () => ({
37+
contents: [
38+
{
39+
uri: "ui://dashboard/view.html",
40+
mimeType: RESOURCE_MIME_TYPE,
41+
text: dashboardHtml,
42+
_meta: {
43+
ui: {
44+
// CSP: tell browser the app is allowed to make requests
45+
csp: {
46+
connectDomains: ["https://api.example.com"],
47+
},
48+
// CORS: give app a stable origin for the API server to allowlist
49+
//
50+
// (Public APIs that use `Access-Control-Allow-Origin: *` or API
51+
// key auth don't need this.)
52+
domain: APP_DOMAIN,
53+
},
54+
},
55+
},
56+
],
57+
}),
58+
);
59+
```
60+
61+
Note that `_meta.ui.csp` and `_meta.ui.domain` are set in the `contents[]` objects returned by the resource read callback, not in `registerAppResource()`'s config object.
62+
63+
> [!NOTE]
64+
> For full examples that configures CSP, see: [`examples/sheet-music-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/sheet-music-server) (`connectDomains`) and [`examples/map-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/map-server) (`connectDomains` and `resourceDomains`).

‎docs/migrate_from_openai_apps.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
title: Migrate OpenAI App
3+
description: Migrate from the OpenAI Apps SDK to MCP Apps SDK with concept mapping tables, API equivalents, and complete before/after code examples.
34
---
45

56
# Migrating from OpenAI Apps SDK to MCP Apps SDK

‎docs/overview.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
title: Overview
3+
description: MCP Apps extends the Model Context Protocol to let MCP servers deliver interactive UIs — charts, forms, dashboards — rendered securely in iframes inside any compliant host.
34
---
45

56
# MCP Apps Overview

‎docs/patterns.md‎

Lines changed: 2 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
title: Patterns
3+
description: Common patterns and recipes for building MCP Apps — polling, chunked data, binary resources, theming, fullscreen, model context, state persistence, and more.
34
---
45

56
# MCP Apps Patterns
@@ -298,62 +299,7 @@ videoEl.src = `data:${content.mimeType!};base64,${content.blob}`;
298299
299300
## Configuring CSP and CORS
300301

301-
Unlike regular web apps, MCP Apps HTML is served as an MCP resource and runs in a sandboxed iframe with no same-origin server. Any app that makes network requests must configure Content Security Policy (CSP) and possibly CORS.
302-
303-
**CSP** controls what the _browser_ allows. You must declare _all_ origins in {@link types!McpUiResourceMeta.csp `_meta.ui.csp`} ({@link types!McpUiResourceCsp `McpUiResourceCsp`}) — including `localhost` during development. Declare `connectDomains` for fetch/XHR/WebSocket requests and `resourceDomains` for scripts, stylesheets, images, and fonts.
304-
305-
**CORS** controls what the _API server_ allows. Public APIs that respond with `Access-Control-Allow-Origin: *` or use API key authentication work without CORS configuration. For APIs that allowlist specific origins, use {@link types!McpUiResourceMeta.domain `_meta.ui.domain`} to give the app a stable origin that the API server can allowlist. The format is host-specific, so check each host's documentation for its supported format.
306-
307-
<!-- prettier-ignore -->
308-
```ts source="../src/server/index.examples.ts#registerAppResource_withDomain"
309-
// Computes a stable origin from an MCP server URL for hosting in Claude.
310-
function computeAppDomainForClaude(mcpServerUrl: string): string {
311-
const hash = crypto
312-
.createHash("sha256")
313-
.update(mcpServerUrl)
314-
.digest("hex")
315-
.slice(0, 32);
316-
return `${hash}.claudemcpcontent.com`;
317-
}
318-
319-
const APP_DOMAIN = computeAppDomainForClaude("https://example.com/mcp");
320-
321-
registerAppResource(
322-
server,
323-
"Company Dashboard",
324-
"ui://dashboard/view.html",
325-
{
326-
description: "Internal dashboard with company data",
327-
},
328-
async () => ({
329-
contents: [
330-
{
331-
uri: "ui://dashboard/view.html",
332-
mimeType: RESOURCE_MIME_TYPE,
333-
text: dashboardHtml,
334-
_meta: {
335-
ui: {
336-
// CSP: tell browser the app is allowed to make requests
337-
csp: {
338-
connectDomains: ["https://api.example.com"],
339-
},
340-
// CORS: give app a stable origin for the API server to allowlist
341-
//
342-
// (Public APIs that use `Access-Control-Allow-Origin: *` or API
343-
// key auth don't need this.)
344-
domain: APP_DOMAIN,
345-
},
346-
},
347-
},
348-
],
349-
}),
350-
);
351-
```
352-
353-
Note that `_meta.ui.csp` and `_meta.ui.domain` are set in the `contents[]` objects returned by the resource read callback, not in `registerAppResource()`'s config object.
354-
355-
> [!NOTE]
356-
> For full examples that configures CSP, see: [`examples/sheet-music-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/sheet-music-server) (`connectDomains`) and [`examples/map-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/map-server) (`connectDomains` and `resourceDomains`).
302+
See the dedicated [CSP & CORS](./csp-cors.md) guide in the Security section.
357303

358304
## Adapting to host context (theme, styling, fonts, and safe areas)
359305

‎docs/quickstart.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
title: Quickstart
3+
description: Build your first MCP App step by step — create an MCP server with an interactive View that renders inside Claude Desktop and other MCP hosts.
34
---
45

56
# Build Your First MCP App

‎docs/testing-mcp-apps.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
title: Testing MCP Apps
3+
description: Test MCP Apps locally with the basic-host reference implementation or in production hosts like Claude.ai and VS Code.
34
---
45

56
# Test Your MCP App

0 commit comments

Comments
 (0)