Addon MCP: Make endpoint configurable

[kasperpeulen]

TL;DR

Adds an optional endpoint option to @storybook/addon-mcp so the addon dev server can serve MCP somewhere other than /mcp.

Default behavior is unchanged: without endpoint, the addon still registers /mcp. The option only configures the local addon route; composed remote refs and OAuth metadata keep the existing /mcp behavior.

Companion PR: storybookjs/storybook#34863.

Usage

// .storybook/main.ts
export default {
  addons: [
    {
      name: '@storybook/addon-mcp',
      options: { endpoint: '/tools/mcp' },
    },
  ],
};

Review Map

Start with the behavior surface:

1. packages/addon-mcp/src/types.ts parses endpoint?: string as a URL pathname.
2. packages/addon-mcp/src/preset.ts applies the parsed endpoint to the addon GET/POST MCP routes.
3. packages/mcp/src/utils/get-manifest.ts keeps Storybook manifests top-level by deriving /manifests/... from the request origin, independent of the MCP endpoint path.

Tests to review next:

• packages/addon-mcp/src/types.test.ts covers endpoint parsing and rejection directly at the schema boundary.
• packages/addon-mcp/src/preset.test.ts covers default /mcp, custom endpoints, no-refs behavior, and refs/local-manifest behavior.
• packages/mcp/src/utils/get-manifest.test.ts covers manifest URL resolution for default, trailing slash, nested custom endpoint, prefixed path, and localhost custom endpoint requests.
• packages/addon-mcp/src/auth/composition-auth.test.ts only adds stubGlobal cleanup; composition-auth.ts itself is not changed in the final diff.

Docs/release notes:

• packages/addon-mcp/README.md documents addon configuration.
• README.md mentions the configured endpoint in local debug instructions.
• .changeset/quiet-rivers-connect.md marks the new addon option as a minor change.

Mechanical/CI-required:

• pnpm-workspace.yaml and generated lockfiles refresh Storybook packages from 10.5.0-alpha.1 to 10.5.0-alpha.2; the repo dependency freshness test requires this.

Non-goals

• No runtime metadata preset is added in this PR.
• No remote-ref custom endpoint contract is added.
• No OAuth protected-resource metadata behavior is changed.
• Manifest files are not moved under the MCP endpoint. They remain Storybook top-level /manifests/... resources.

Review Notes

This branch is now a single focused commit. Review the final Files changed diff in the order above: option schema, route wiring, shared manifest URL derivation, tests, docs, then generated lockfile/catalog refreshes.

Validation

Local checks run on this branch:

pnpm vitest run --project=@storybook/mcp packages/mcp/src/utils/get-manifest.test.ts
pnpm vitest run --project=@storybook/addon-mcp packages/addon-mcp/src/preset.test.ts packages/addon-mcp/src/types.test.ts packages/addon-mcp/src/auth/composition-auth.test.ts
pnpm --filter @storybook/addon-mcp typecheck
pnpm format:check
pnpm lint
git diff --check

pnpm lint has 0 errors and the same 2 unrelated warnings in untouched test files.

[netlify]

✅ Deploy Preview for storybook-mcp-self-host-example canceled.

Name	Link
🔨 Latest commit	e68bf67
🔍 Latest deploy log	https://app.netlify.com/projects/storybook-mcp-self-host-example/deploys/6a117a7302954700085cfb31

[pkg-pr-new]

npx https://pkg.pr.new/storybookjs/mcp/@storybook/addon-mcp@233

npx https://pkg.pr.new/storybookjs/mcp/@storybook/mcp@233

npx https://pkg.pr.new/storybookjs/mcp/@storybook/mcp-proxy@233

commit: e68bf67

[codecov]

Codecov Report

❌ Patch coverage is 95.23810% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 76.46%. Comparing base (51afdf7) to head (e39945e).

Files with missing lines	Patch %	Lines
packages/addon-mcp/src/types.ts	80.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #233      +/-   ##
==========================================
+ Coverage   76.06%   76.46%   +0.39%     
==========================================
  Files          52       52              
  Lines        1412     1419       +7     
  Branches      391      394       +3     
==========================================
+ Hits         1074     1085      +11     
+ Misses        205      203       -2     
+ Partials      133      131       -2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[changeset-bot]

🦋 Changeset detected

Latest commit: e68bf67

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@storybook/addon-mcp	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[codecov]

Bundle Report

Changes will decrease total bundle size by 41 bytes (-0.05%) ⬇️. This is within the configured threshold ✅

Detailed changes

Bundle name	Size	Change
@storybook/mcp-esm	48.44kB	-41 bytes (-0.08%) ⬇️

Affected Assets, Files, and Routes:

view changes for bundle: @storybook/mcp-esm

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
index.js	-63 bytes	31.89kB	-0.2%
index.d.ts	22 bytes	15.34kB	0.14%

Files in index.js:

• ./src/types.ts → Total Size: 2.06kB

• ./src/utils/get-manifest.ts → Total Size: 6.22kB

[Copilot]

Pull request overview

This PR adds a new endpoint addon option to @storybook/addon-mcp, allowing the MCP HTTP route to be served somewhere other than /mcp while keeping /mcp as the default. It also updates OAuth protected-resource metadata generation and adds test coverage + a Changesets entry for the new option.

Changes:

• Add endpoint?: string to addon options schema and wire it into the preset’s dev server route registration (GET/POST).
• Update .well-known/oauth-protected-resource generation to use the configured endpoint.
• Add unit tests for the configurable route and OAuth metadata, plus a minor Changesets entry.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/addon-mcp/src/types.ts	Adds endpoint to the addon options Valibot schema/types.
packages/addon-mcp/src/preset.ts	Uses the configured endpoint for MCP GET/POST and passes it into OAuth well-known generation.
packages/addon-mcp/src/preset.test.ts	Tests registering a custom MCP endpoint route.
packages/addon-mcp/src/auth/composition-auth.ts	Uses the configured endpoint when building protected-resource metadata.
packages/addon-mcp/src/auth/composition-auth.test.ts	Updates tests to cover the new buildWellKnown signature.
.changeset/quiet-rivers-connect.md	Declares a minor release for the new addon option.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

packages/addon-mcp/src/preset.ts:41

• With a custom endpoint, requests will have request.url ending in that endpoint (e.g. /custom-mcp). The docs tools reused from @storybook/mcp derive manifest URLs by replacing a trailing /mcp in request.url (see packages/mcp/src/utils/get-manifest.ts), so in single-source mode (no refs) manifest fetching will break and attempt to fetch manifests from the MCP endpoint path. To keep docs tools working when endpoint is customized, create a manifestProvider unconditionally (e.g. via compositionAuth.createManifestProvider(origin)) instead of only when refs are configured.

	// Get composed Storybook refs from config
	const refs = await getRefsFromConfig(options);
	const compositionAuth = new CompositionAuth();

	// Build sources and manifest provider only if refs are configured

[Copilot]

Pull request overview

Copilot reviewed 7 out of 10 changed files in this pull request and generated 2 comments.

Files not reviewed (3)

• apps/internal-storybook/pnpm-lock.yaml: Language not supported
• eval/pnpm-lock.yaml: Language not supported
• packages/addon-mcp/pnpm-lock.yaml: Language not supported

[Copilot]

Pull request overview

Copilot reviewed 7 out of 10 changed files in this pull request and generated 1 comment.

Files not reviewed (3)

• apps/internal-storybook/pnpm-lock.yaml: Language not supported
• eval/pnpm-lock.yaml: Language not supported
• packages/addon-mcp/pnpm-lock.yaml: Language not supported

[Copilot]

Pull request overview

Copilot reviewed 10 out of 13 changed files in this pull request and generated 2 comments.

Files not reviewed (3)

• apps/internal-storybook/pnpm-lock.yaml: Language not supported
• eval/pnpm-lock.yaml: Language not supported
• packages/addon-mcp/pnpm-lock.yaml: Language not supported

[Copilot]

Pull request overview

Copilot reviewed 9 out of 12 changed files in this pull request and generated 3 comments.

Files not reviewed (3)

• apps/internal-storybook/pnpm-lock.yaml: Language not supported
• eval/pnpm-lock.yaml: Language not supported
• packages/addon-mcp/pnpm-lock.yaml: Language not supported

Comments suppressed due to low confidence (1)

packages/addon-mcp/src/auth/composition-auth.ts:143

• Changing buildWellKnown(origin: string) to buildWellKnown({ origin, endpoint }) is a breaking public API change for any external consumers constructing CompositionAuth directly (it’s exported). If you want to avoid a breaking change, consider keeping the original signature (and optionally adding an overload/new method) so existing callers continue to work while enabling the new endpoint-aware behavior.

	/** Build .well-known/oauth-protected-resource response. */
	buildWellKnown({
		origin,
		endpoint = DEFAULT_MCP_ENDPOINT,
	}: {
		origin: string;
		endpoint?: string;
	}): object | null {
		if (!this.#authRequirement) return null;
		return {
			resource: this.#buildMcpEndpointUrl(origin, endpoint),
			authorization_servers: this.#authRequirement.resourceMetadata.authorization_servers,
			scopes_supported: this.#authRequirement.resourceMetadata.scopes_supported,
		};
	}

[Copilot]

Pull request overview

Copilot reviewed 16 out of 19 changed files in this pull request and generated 2 comments.

Files not reviewed (3)

• apps/internal-storybook/pnpm-lock.yaml: Language not supported
• eval/pnpm-lock.yaml: Language not supported
• packages/addon-mcp/pnpm-lock.yaml: Language not supported

[Copilot]

Pull request overview

Copilot reviewed 12 out of 15 changed files in this pull request and generated 1 comment.

Files not reviewed (3)

• apps/internal-storybook/pnpm-lock.yaml: Language not supported
• eval/pnpm-lock.yaml: Language not supported
• packages/addon-mcp/pnpm-lock.yaml: Language not supported

Comments suppressed due to low confidence (1)

packages/addon-mcp/src/auth/composition-auth.ts:296

• new URL(DEFAULT_MCP_ENDPOINT, origin) also drops any base pathname (e.g. https://host/storybook -> https://host/mcp). Here origin is effectively a base URL for the Storybook instance (can include a path), so this can mis-detect auth requirements when Storybook is hosted under a sub-path. Append DEFAULT_MCP_ENDPOINT to the provided base URL instead.

	/** Quick check: does the remote MCP endpoint return 401? */
	async #isMcpUnauthorized(origin: string): Promise<boolean> {
		try {
			const response = await fetch(new URL(DEFAULT_MCP_ENDPOINT, origin).toString(), {
				method: 'POST',
				headers: { 'Content-Type': 'application/json' },
				body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list' }),
			});

[codecov]

Codecov Report

❌ Patch coverage is 92.30769% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 76.21%. Comparing base (51afdf7) to head (e68bf67).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
packages/addon-mcp/src/types.ts	80.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #233      +/-   ##
==========================================
+ Coverage   76.06%   76.21%   +0.15%     
==========================================
  Files          52       52              
  Lines        1412     1417       +5     
  Branches      391      393       +2     
==========================================
+ Hits         1074     1080       +6     
  Misses        205      205              
+ Partials      133      132       -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 15 changed files in this pull request and generated 1 comment.

Files not reviewed (3)

• apps/internal-storybook/pnpm-lock.yaml: Language not supported
• eval/pnpm-lock.yaml: Language not supported
• packages/addon-mcp/pnpm-lock.yaml: Language not supported

[Copilot]

Pull request overview

Copilot reviewed 12 out of 15 changed files in this pull request and generated 2 comments.

Files not reviewed (3)

• apps/internal-storybook/pnpm-lock.yaml: Language not supported
• eval/pnpm-lock.yaml: Language not supported
• packages/addon-mcp/pnpm-lock.yaml: Language not supported

[Copilot]

Pull request overview

Copilot reviewed 12 out of 15 changed files in this pull request and generated no new comments.

Files not reviewed (3)

• apps/internal-storybook/pnpm-lock.yaml: Language not supported
• eval/pnpm-lock.yaml: Language not supported
• packages/addon-mcp/pnpm-lock.yaml: Language not supported