Public: anyone can read this; the crew can change it.

/.well-known/mcp/server-card.json tells an agent what the MCP is and how to sign in #13121

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

scout/forge:scout/13112-well-known-mcp-server-card-json-tells-an → main 5 commits fork

  • Merged. scout/13112-well-known-mcp-server-card-json-tells-an was merged into main as e4ac986.

Review

Sign in to review this change.
7 files changed +163 −31
docs/MCP.md +2
@@ -473,6 +473,8 @@ Any MCP client that can send a header works the same way.
473473
474474 ## The server card
475475
476 `/.well-known/mcp/server-card.json` is the small one (the MCP server-card draft, SEP-1649; its names may change): `name`, `version`, `endpoint`, `transport`, `authorization` (read from `/.well-known/oauth-protected-resource`), and only the tools a stranger may call. Public, cached an hour, linked from `/llms.txt` and `mcp` in `/api/v1/here`.
477
476478 `/.well-known/mcp.json` names the server (`name`, `version`, `endpoint`,
477479 `transport`, `protectedResourceMetadata`, `documentation`, `openapi`,
478480 `tokenFreeTools`)
src/core/mcp_card.ts +59 −5
@@ -14,18 +14,36 @@ import { repoVisibility } from "./repos.ts";
1414 import { CARD_OF_TOOL, CARD_URI } from "../web/studio/cards.ts";
1515
1616 /** The endpoint and the protected-resource metadata that names how to sign in. */
17 export function mcpPointers(origin: string): { url: string; oauth: string } {
17 export function mcpPointers(origin: string): { url: string; oauth: string; card: string } {
1818 return {
1919 url: `${origin}${DISCOVERY.mcp}`,
2020 oauth: `${origin}/.well-known/oauth-protected-resource`,
21 card: `${origin}${DISCOVERY.serverCard}`,
2122 };
2223 }
2324
24 /** The paths the discovery documents name each other by; the card, the API catalog and /llms.txt read them, so they cannot drift. */
25 /** The OAuth scopes are the oauth module's; the document at
26 * /.well-known/oauth-protected-resource is made here so the server card reads the very same one. */
27 export function protectedResource(origin: string, scopes: readonly string[]) {
28 return {
29 resource: `${origin}/mcp`,
30 resource_name: "forge",
31 resource_documentation: `${origin}/llms.txt`,
32 authorization_servers: [origin],
33 scopes_supported: [...scopes],
34 bearer_methods_supported: ["header"],
35 };
36 }
37
38 /**
39 * The paths the discovery documents name each other by; the card, the API catalog and /llms.txt
40 * read them, so they cannot drift.
41 */
2542 export const DISCOVERY = {
2643 openapi: "/contract/openapi.json",
2744 docs: "/llms.txt",
2845 card: "/.well-known/mcp.json",
46 serverCard: "/.well-known/mcp/server-card.json",
2947 agentCard: "/.well-known/agent-card.json",
3048 catalog: "/.well-known/api-catalog",
3149 mcp: "/mcp",
@@ -65,9 +83,15 @@ export interface HarnessPlugin {
6583 readonly harness: string;
6684 readonly label: string;
6785 readonly path: string;
68 /** True when the install clones the source repository (so it needs one offered); false when this forge serves the file itself. */
86 /**
87 * True when the install clones the source repository (so it needs one offered); false when this
88 * forge serves the file itself.
89 */
6990 readonly cloned: boolean;
70 /** The one line, given the origin it was read from and the source repository; it works in an empty directory. */
91 /**
92 * The one line, given the origin it was read from and the source repository; it works in an empty
93 * directory.
94 */
7195 readonly install: (origin: string, repo: string) => string;
7296 /** What to set before it runs. */
7397 readonly setup: string;
@@ -111,7 +135,10 @@ export const HARNESS_PLUGINS: readonly HarnessPlugin[] = [
111135 },
112136 ];
113137
114 /** The plugins this forge can offer: the ones it serves itself always, the cloned ones only while a public source exists. */
138 /**
139 * The plugins this forge can offer: the ones it serves itself always, the cloned ones only while a
140 * public source exists.
141 */
115142 export function offeredPlugins(repo: string | undefined): readonly HarnessPlugin[] {
116143 return HARNESS_PLUGINS.filter((p) => !p.cloned || repo !== undefined);
117144 }
@@ -235,3 +262,30 @@ export function mcpCard(origin: string, repo: string | undefined, now: Running =
235262 })),
236263 };
237264 }
265
266 /**
267 * The small server card at /.well-known/mcp/server-card.json. It follows the
268 * MCP server-card draft (SEP-1649, a draft: field names may change), keeping
269 * only what we can hold true: name, version, the endpoint, the transport and
270 * the authorization server read from the protected-resource document. It
271 * lists only the tools a stranger may call (never one that needs an account
272 * or a role), so every reader gets the same card.
273 */
274 export function serverCard(origin: string, scopes: readonly string[], now: Running = running()) {
275 const pr = protectedResource(origin, scopes);
276 return {
277 name: "forge",
278 version: now.version,
279 endpoint: pr.resource,
280 transport: "streamable-http",
281 authorization: {
282 type: "oauth2",
283 protectedResourceMetadata: mcpPointers(origin).oauth,
284 authorization_servers: pr.authorization_servers,
285 scopes_supported: pr.scopes_supported,
286 },
287 documentation: pr.resource_documentation,
288 tools: [...TOKEN_FREE_TOOLS],
289 fullCard: `${origin}${DISCOVERY.card}`,
290 };
291 }
src/http/oauth.ts +5 −13
@@ -9,6 +9,7 @@
99 * checked on its POST.
1010 */
1111 import type { App } from "../app.ts";
12 import { protectedResource } from "../core/mcp_card.ts";
1213 import {
1314 createClient,
1415 OAUTH_SCOPES,
@@ -28,7 +29,9 @@ import { authorizePage, authorizeSubmit } from "../web/pages/oauth.ts";
2829
2930 /** Registrations per address per minute. */
3031 const REGISTER_PER_MINUTE = 10;
31 /** Revocations per address per minute: a token is 40 random characters, not guessable at this rate. */
32 /**
33 * Revocations per address per minute: a token is 40 random characters, not guessable at this rate.
34 */
3235 const REVOKE_PER_MINUTE = 60;
3336 /** Revocations per minute across every address: the whole-forge cap beside the per-address one. */
3437 const REVOKE_ALL_PER_MINUTE = 600;
@@ -205,18 +208,7 @@ export function oauthRoutes(router: Router<Handler>): void {
205208 ),
206209 );
207210 router.add("GET", "/.well-known/oauth-protected-resource", (ctx) =>
208 json(
209 {
210 resource: `${ctx.url.origin}/mcp`,
211 resource_name: "forge",
212 resource_documentation: `${ctx.url.origin}/llms.txt`,
213 authorization_servers: [ctx.url.origin],
214 scopes_supported: [...OAUTH_SCOPES],
215 bearer_methods_supported: ["header"],
216 },
217 200,
218 docHeaders,
219 ),
211 json(protectedResource(ctx.url.origin, OAUTH_SCOPES), 200, docHeaders),
220212 );
221213 router.add("GET", "/.well-known/oauth-authorization-server", (ctx) =>
222214 json(
src/http/server.ts +11 −5
@@ -209,6 +209,7 @@ import {
209209 securityTxt,
210210 apiCatalogJson,
211211 mcpJson,
212 serverCardJson,
212213 agentCardJson,
213214 forgeJson,
214215 sitemapXml,
@@ -838,6 +839,7 @@ export function buildRouter(): Router<Handler> {
838839 // What the open web expects of a site, from the forge's own facts.
839840 router.add("GET", "/.well-known/security.txt", securityTxt);
840841 router.add("GET", "/.well-known/mcp.json", mcpJson);
842 router.add("GET", "/.well-known/mcp/server-card.json", serverCardJson);
841843 router.add("GET", "/.well-known/agent-card.json", agentCardJson);
842844 router.add("GET", "/.well-known/api-catalog", apiCatalogJson);
843845 router.add("GET", "/.well-known/forge", forgeJson);
@@ -912,7 +914,8 @@ export function buildRouter(): Router<Handler> {
912914 router.add("GET", "/", home);
913915 // The home is `/`; its old address goes there (web/pages/home_flow.ts). Literal, above /:owner.
914916 router.add("GET", "/home", homeRedirect);
915 // The new home's action bar: preview or apply one bulk action over the rows picked (web/pages/home_table.ts).
917 // The new home's action bar: preview or apply one bulk action over the rows picked
918 // (web/pages/home_table.ts).
916919 router.add("POST", "/home/act", homeActPost);
917920 router.add("POST", "/desk", deskLeave);
918921 router.add("POST", "/desk/clear", deskClear);
@@ -1044,7 +1047,8 @@ export function buildRouter(): Router<Handler> {
10441047 router.add("GET", "/new/issue", newIssueAnywhere);
10451048 router.add("GET", "/repos", myReposPage);
10461049 router.add("GET", "/displays", displaysPage);
1047 // A repository's display, read only (`display.ts`): 404 without a display.json or without read access.
1050 // A repository's display, read only (`display.ts`): 404 without a display.json or without read
1051 // access.
10481052 router.add("GET", "/:owner/:name/display", displayPage);
10491053 router.add("POST", "/:owner/:name/display", displayChoose);
10501054 router.add("GET", "/now/:stage", nowPage);
@@ -1080,8 +1084,9 @@ export function buildRouter(): Router<Handler> {
10801084 router.add("GET", "/migrate/jobs/:job", migrationJobPage);
10811085 // Every app on one canvas; a literal route, so it must sit above /:owner.
10821086 router.add("GET", "/map", globalMapPage);
1083 // The pipeline moved to a panel on /boards (#2774); the old address follows it. Literal, above /:owner.
1084 // /flow is the week's valves (#8698); a query string is an old pipeline drill, which went to /boards.
1087 // The pipeline moved to a panel on /boards (#2774); the old address follows it. Literal, above
1088 // /:owner. /flow is the week's valves (#8698); a query string is an old pipeline drill, which
1089 // went to /boards.
10851090 router.add("GET", "/flow", flowPage);
10861091 router.add("POST", "/flow/valve", valveSet);
10871092 router.add("POST", "/flow/backup/retry", backupRetry);
@@ -2733,7 +2738,8 @@ export async function serve(app: App): Promise<Servers> {
27332738 });
27342739 // The minute ledger's history: one write a minute, never on a request.
27352740 const trafficWriter = createTrafficWriter(app.db, liveOf(app).perfRecord.ledger, app.log);
2736 // Page views are buffered by the beacon doors and written here; GitHub's traffic is pulled daily when a token is set.
2741 // Page views are buffered by the beacon doors and written here; GitHub's traffic is pulled daily
2742 // when a token is set.
27372743 const viewWriter = createViewWriter(app.db, app.log);
27382744 const githubPull = startGithubPull(app.db, app.log);
27392745 const featureSchedule = startFeatureSchedule(app);
src/web/standards.ts +29 −7
@@ -3,6 +3,7 @@
33 * by default so a forge is a good citizen the moment it boots:
44 *
55 * /.well-known/security.txt who to tell about a vulnerability (RFC 9116)
6 * /.well-known/mcp/server-card.json the small MCP server card (a draft)
67 * /.well-known/mcp.json the MCP server card: endpoint, sign-in, the
78 * tool that needs no token (a draft format:
89 * only fields we keep true)
@@ -50,7 +51,8 @@ import { SITE_PATH, SITE_LINE } from "./site_line.ts";
5051 import { holds } from "./feeds.ts";
5152 import { mcpToolsSection, mcpToolsVersion, readerKey, type Reader } from "./llms_tools.ts";
5253 import { threeDoors } from "./doors_words.ts";
53 import { agentCard, toolsKey, apiCatalog, cardsLine, DISCOVERY, mcpCard, offeredPlugins, mcpPointers, offeredPluginRepo, pluginSource } from "../core/mcp_card.ts";
54 import { OAUTH_SCOPES } from "../core/oauth.ts";
55 import { agentCard, serverCard, toolsKey, apiCatalog, cardsLine, DISCOVERY, mcpCard, offeredPlugins, mcpPointers, offeredPluginRepo, pluginSource } from "../core/mcp_card.ts";
5456 import { forgeDocument } from "../core/standards_index.ts";
5557 import { TAGS } from "../contract/served.ts";
5658 import { running } from "../kernel/version.ts";
@@ -131,7 +133,10 @@ export function securityTxt(ctx: Ctx): Response {
131133 );
132134 }
133135
134 /** A discovery document and its ETag, per kind and origin, made again only when its inputs read differently. */
136 /**
137 * A discovery document and its ETag, per kind and origin, made again only when its inputs read
138 * differently.
139 */
135140 const discoveryBodies = new Map<string, { inputs: string; body: string; etag: string }>();
136141
137142 /**
@@ -147,7 +152,8 @@ function discovery(ctx: Ctx, kind: string, inputs: string, make: () => unknown,
147152 const etag = `"${new Bun.CryptoHasher("sha256").update(body).digest("hex").slice(0, 32)}"`;
148153 kept = { inputs, body, etag };
149154 // Origins come from the Host header: keep a handful, not one per guess.
150 // The oldest goes first (a Map keeps insertion order), so junk hosts never flush the real ones at once.
155 // The oldest goes first (a Map keeps insertion order), so junk hosts never flush the real ones
156 // at once.
151157 discoveryBodies.delete(key);
152158 if (discoveryBodies.size >= 48) discoveryBodies.delete(discoveryBodies.keys().next().value!);
153159 discoveryBodies.set(key, kept);
@@ -165,6 +171,13 @@ export async function mcpJson(ctx: Ctx): Promise<Response> {
165171 return discovery(ctx, "mcp", JSON.stringify([repo, now.version, now.commit, toolsKey()]), () => mcpCard(ctx.url.origin, repo, now), "application/json", "public, max-age=3600", true);
166172 }
167173
174 /** GET /.well-known/mcp/server-card.json — the small server card (a draft; see `serverCard`).
175 * Public, the same for every reader. */
176 export function serverCardJson(ctx: Ctx): Response {
177 const now = running();
178 return discovery(ctx, "server-card", JSON.stringify([now.version]), () => serverCard(ctx.url.origin, OAUTH_SCOPES, now), "application/json", "public, max-age=3600", true);
179 }
180
168181 /**
169182 * GET /.well-known/agent-card.json — the A2A agent card, its skills the MCP
170183 * tool names the server card lists.
@@ -177,12 +190,18 @@ export async function agentCardJson(ctx: Ctx): Promise<Response> {
177190 return discovery(ctx, `agent-card ${signedIn}`, JSON.stringify([now.version, toolsKey()]), () => agentCard(ctx.url.origin, now, signedIn), "application/json", signedIn ? "private, max-age=3600" : "public, max-age=3600", true, "Cookie, Authorization");
178191 }
179192
180 /** GET /.well-known/api-catalog — RFC 9727: one linkset naming each API's description and docs. Anonymous. */
193 /**
194 * GET /.well-known/api-catalog — RFC 9727: one linkset naming each API's description and docs.
195 * Anonymous.
196 */
181197 export function apiCatalogJson(ctx: Ctx): Response {
182198 return discovery(ctx, "api-catalog", "", () => apiCatalog(ctx.url.origin), 'application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727"', "public, max-age=300");
183199 }
184200
185 /** GET /.well-known/forge — the standards this forge implements, by id and version (docs/standards/). */
201 /**
202 * GET /.well-known/forge — the standards this forge implements, by id and version
203 * (docs/standards/).
204 */
186205 export function forgeJson(ctx: Ctx): Response {
187206 const version = running().version;
188207 return discovery(ctx, "forge", version, () => forgeDocument(version), "application/json", "public, max-age=3600");
@@ -419,7 +438,10 @@ function runningSentence(): string {
419438 : `Running ${r.version} at ${r.commit.slice(0, 7)}`;
420439 }
421440
422 /** llms.txt and its ETag per origin, valid while the listing read, the build, the tell command and the plugin source being public are the same. */
441 /**
442 * llms.txt and its ETag per origin, valid while the listing read, the build, the tell command and
443 * the plugin source being public are the same.
444 */
423445 const llmsBodies = new Map<string, { repos: LlmsListing; running: string; tell: string | undefined; plugins: string | undefined; plans: string; tools: number; body: string; etag: string }>();
424446
425447 /**
@@ -556,7 +578,7 @@ function renderLlmsTxt(ctx: Ctx, o: string, tell: string | undefined, running: s
556578 "",
557579 "## For agents with an account",
558580 "",
559 `- MCP: ${mcp.url} (OAuth discovery: ${mcp.oauth}; server card, a draft format: ${o}${DISCOVERY.card}; A2A agent card: ${o}${DISCOVERY.agentCard})`,
581 `- MCP: ${mcp.url} (OAuth discovery: ${mcp.oauth}; server card, a draft format: ${o}${DISCOVERY.serverCard} (fuller: ${o}${DISCOVERY.card}); A2A agent card: ${o}${DISCOVERY.agentCard})`,
560582 `- API: ${o}${DISCOVERY.api} (the root lists the other URLs), Authorization: Bearer <token>`,
561583 `- API catalog (RFC 9727, one linkset of the above): ${o}${DISCOVERY.catalog}`,
562584 `- OpenAPI: GET ${o}${DISCOVERY.openapi}, or one slice with ?tag= (${TAGS.join(", ")})`,
test/mcp-card.test.ts +1 −1
@@ -87,7 +87,7 @@ describe("the MCP server card", () => {
8787 test("the `mcp` block of /api/v1/here gives the same url and oauth", async () => {
8888 const card = (await (await fetch(`${base}/.well-known/mcp.json`)).json()) as any;
8989 const here = (await (await fetch(`${base}/api/v1/here?path=/`)).json()) as any;
90 expect(here.mcp).toEqual({ url: card.endpoint, oauth: card.protectedResourceMetadata });
90 expect(here.mcp).toEqual({ url: card.endpoint, oauth: card.protectedResourceMetadata, card: `${base}/.well-known/mcp/server-card.json` });
9191 });
9292
9393 test("/llms.txt links the card", async () => {
test/mcp-server-card.test.ts added +56
@@ -0,0 +1,56 @@
1 /** /.well-known/mcp/server-card.json: small, public, cached, its endpoint the request's own host,
2 * its sign-in read from the protected-resource document. */
3 import { afterAll, beforeAll, expect, test } from "bun:test";
4 import { mkdtemp, rm } from "node:fs/promises";
5 import { tmpdir } from "node:os";
6 import { join } from "node:path";
7 import { createApp } from "../src/app.ts";
8 import { serve, type Servers } from "../src/http/server.ts";
9 import { TOKEN_FREE_TOOLS } from "../src/core/mcp_card.ts";
10
11 let dataDir: string;
12 let servers: Servers;
13 let base: string;
14 const path = "/.well-known/mcp/server-card.json";
15
16 beforeAll(async () => {
17 dataDir = await mkdtemp(join(tmpdir(), "forge-server-card-"));
18 servers = await serve(createApp({ dataDir, port: 0 }));
19 base = servers.url;
20 });
21 afterAll(async () => {
22 await servers.stop?.();
23 await rm(dataDir, { recursive: true, force: true });
24 });
25
26 test("answers 200 JSON, public and cached, with name, version, endpoint and the authorization server", async () => {
27 const res = await fetch(base + path);
28 expect(res.status).toBe(200);
29 expect(res.headers.get("content-type")).toContain("application/json");
30 expect(res.headers.get("cache-control")).toBe("public, max-age=3600");
31 const card = (await res.json()) as any;
32 expect(card.name).toBe("forge");
33 expect(typeof card.version).toBe("string");
34 expect(card.endpoint).toBe(`${base}/mcp`);
35 const pr = (await (await fetch(card.authorization.protectedResourceMetadata)).json()) as any;
36 expect(card.authorization.authorization_servers).toEqual(pr.authorization_servers);
37 expect(card.authorization.scopes_supported).toEqual(pr.scopes_supported);
38 expect(card.endpoint).toBe(pr.resource);
39 });
40
41 test("the endpoint is the request's host, not a fixed one", async () => {
42 const card = (await (await fetch(base + path, { headers: { host: "other.example" } })).json()) as any;
43 expect(card.endpoint).toBe("http://other.example/mcp");
44 expect(card.authorization.authorization_servers).toEqual(["http://other.example"]);
45 });
46
47 test("lists only tools a stranger may call", async () => {
48 const card = (await (await fetch(base + path)).json()) as any;
49 expect(card.tools).toEqual([...TOKEN_FREE_TOOLS]);
50 });
51
52 test("/llms.txt and the here manifest link it", async () => {
53 expect(await (await fetch(`${base}/llms.txt`)).text()).toContain(`${base}${path}`);
54 const here = (await (await fetch(`${base}/api/v1/here?path=/`)).json()) as any;
55 expect(here.mcp.card).toBe(`${base}${path}`);
56 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs