[security] Add MCP elicitation for secure preview token handling

[mattpodwysocki]

Summary

Implements MCP elicitation for secure token management in preview_style_tool and style_comparison_tool, following the principle of least privilege. Elicitation ensures that only minimal-scope public tokens (pk.) appear in preview URLs, while your powerful server token (sk.) stays secure.

Update: Rebase onto main, HttpPipeline, and Hosted Endpoint Handling

This branch sat for a while, so it's been rebased onto current main and hardened before merge (see details below for the full file list):

• Rebased onto main - resolved conflicts against the path-traversal fix (encodeURIComponent around username/styleId), the shared styleIdSchema, the now-unconditional MCP-UI meta/CSP block, and _meta.viewUUID. style_comparison_tool elicitation (described throughout this PR) is now actually implemented to match the description below - it wasn't in the original commits.
• Moved off raw fetch() - token listing/creation now go through the shared HttpPipeline (constructor-injected httpRequest), matching every other Mapbox-API-calling tool in this repo, and consolidated the duplicated listing/creation logic from both tools into shared functions in tokenElicitation.ts. This is a constructor signature change for direct consumers - see Breaking Changes.
• Hosted MCP endpoint: creating tokens requires tokens:write on the caller's own access token. A literal Mapbox temporary token (tk.*) never has that scope, so isTemporaryServerToken() detects that shape up front and trims "create"/"auto-create" from the elicitation dialog rather than offering options that are guaranteed to fail. That check is necessarily narrow, though: the hosted MCP endpoint itself authenticates with its own access token (not a Mapbox pk.*/sk.*/tk.* token), which also lacks tokens:write but isn't detectable from its shape. For that case, "create"/"auto-create" still fail against the Tokens API, but the error now includes a scope/permission hint pointing back to "provide an existing token" instead of a bare API error. create_token_tool is disabled entirely on the hosted endpoint (unrelated to this PR).
• New: real HTTP integration test (test/integration/elicitationOverHttp.test.ts) - every other elicitation test fakes tool['server'] directly; this one spins up an actual Streamable HTTP McpServer and drives it with a real Client that answers elicitation/create requests, covering the tk.* trim, the non-tk.*-shaped-token/scope-hint path, and a full auto-create success, for both tools. httpRequest is still mocked, so this stays fully offline.
  • Building it surfaced a separate, real finding: a first attempt used a fresh McpServer per HTTP request - the same "stateless" pattern hosted-mcp-server's own src/routes/mcp.ts uses (sessionIdGenerator: undefined, fresh server per POST) - and every elicitation call failed with "client does not support elicitation" regardless of what the client declared. Server#getClientCapabilities() is only ever populated on whichever Server instance processes the client's initialize request; a fresh server per request means the tools/call request lands on an instance that never saw that handshake. If hosted-mcp-server's production deployment works this way, elicitation may not be functional there at all, independent of the tk.* issue above - that's hosted-mcp-server's architecture, not this PR's tool code, so it's just documented in the test's doc comment rather than addressed here.
• Review feedback addressed (thanks @Valiunia): useCustomToken no longer forces an avoidable error on clients without elicitation support when a valid cached token already exists (it now silently falls back to the cache); previewTokenStorage's cache key is now a sha256 hash of the actual server access token (cacheKeyFor) instead of the unverified username decoded out of it, since getUserNameFromToken never checks a JWT's signature.
• Critical: fixed a cross-session elicitation hijack - see the dedicated section below.
• README/CHANGELOG updated to document the above.
• All 651 tests pass (up from 529 - new coverage for the HttpPipeline refactor, the tk.* dialog-trimming behavior, the HTTP integration test, the review-feedback fixes, and the cross-session-hijack regression test), build and lint are clean. The manual client screenshots below predate this update and haven't been re-captured; see the note under Test Results.

Critical Fix: Cross-Session Elicitation Hijack

While reviewing this PR, a colleague ran an AI review pass (Fable) that surfaced a real vulnerability in how this PR's elicitation code uses this.server, confirmed by tracing through the actual code and reproduced with a regression test:

The bug: BaseTool.installTo(server) does this.server = server — mutable state on the tool instance, not scoped to a single call. CORE_TOOLS (src/tools/toolRegistry.ts) instantiates tools once as module-level singletons. Any deployment that reuses those singleton instances across multiple concurrent sessions — installing the same tool instance onto a new session's McpServer on every connection, which is exactly what CORE_TOOLS/getAllTools() being singletons implies, and what mcp-server's own scripts/dev-http-server.ts and hosted-mcp-server's request handling both do — durably overwrites this.server on every new connection. It ends up pointing at whichever session connected last, not whichever session is making the current call.

Before this PR, this.server was only ever read for logging (harmless if stale). preview_style_tool/style_comparison_tool's elicitation flow was the first thing to read it for something session-sensitive: elicitPreviewToken(this.server.server, ...). Once a second session connects, every subsequent tool call on the shared instance — including one made over an entirely different, already-established session's own connection — sends its "paste your token" elicitation prompt to that other, uninvolved session instead. Whatever that session's client submits comes back as the original caller's tool result: an unprompted-dialog-injection + credential-exfiltration primitive, not a hypothetical.

The fix: elicitation is now routed through the per-call extra.sendRequest (from RequestHandlerExtra, supplied fresh by the SDK on every tool invocation, correctly scoped to whichever session made that request) instead of this.server.server.elicitInput(). extra isn't available to BaseTool.execute() by default, so both tools now override run() to forward it down. This also removes the proactive getClientCapabilities() check (no per-call equivalent exists) in favor of attempting the elicitation request and catching an unsupported-client failure (new ElicitationUnavailableError), which conveniently also simplified the useCustomToken-vs-cache branching from the review-feedback fix above into one attempt-then-fallback path.

Regression test: test/security/cross-session-elicitation-hijack.test.ts spins up one shared PreviewStyleTool instance installed onto two real sessions over real Streamable HTTP (real Client/Server elicitation round trip, no mocked transport). Session A connects, then session B connects (reusing the same tool instance), then session A calls the tool over its own already-established connection. Pre-fix this failed exactly as predicted (session A's elicitation handler: 0 calls; session B's: 1 call). Post-fix it passes.

The Security Problem

Previously, preview_style_tool and style_comparison_tool required users to provide an accessToken directly in the tool input, which created security and UX risks:

• ⚠️ Risk of exposing powerful server token - Users might accidentally pass through their server token (sk.*) with write permissions
• ⚠️ Over-privileged tokens - Users might manually provide tokens with more permissions than needed
• ❌ No guided workflow for token selection
• ❌ Users had to manually create and manage tokens
• ❌ Token management friction

The Solution: Elicitation with Least Privilege

This PR implements MCP elicitation to enforce the principle of least privilege:

• Server token stays secure - Your powerful secret token (sk.*) with write permissions NEVER appears in chat history or URLs
• Minimal-scope public tokens - Preview URLs only contain read-only public tokens (pk.*) with scopes: styles:read, styles:tiles, fonts:read
• Acceptable security trade-off - Even if preview URLs are shared, they only expose read-only access to styles, not your admin token

How It Works

When a user calls preview_style_tool or style_comparison_tool without providing an accessToken:

1. Check for cached token - If a preview token was already created this session, use it
2. Elicit token from user - Present a guided dialog with three options:
   • Provide existing token - User pastes a public token they already have
   • Create new preview token - System creates a new token with optional URL restrictions
   • Auto-create basic token - System auto-creates a simple preview token (recommended)
3. Cache for session - Store token in memory to avoid re-prompting
4. Generate preview/comparison URL - Use the minimal-scope public token in the URL

Key Security Properties:

• Server token (sk.*) is only used server-side to create limited tokens via Mapbox API
• Created tokens are always public (pk.*) with minimal read-only scopes
• No risk of exposing write permissions (styles:write, tokens:write, etc.)

Testing

Test Case 1: First Time Preview (Elicitation Shown)

Steps:

1. Start MCP server with valid Mapbox token
2. Call preview_style_tool with only styleId (no accessToken)
3. Observe elicitation dialog with three options
4. Select "Auto-create a basic preview token for me"
5. Verify preview URL is generated

Expected:

• Elicitation dialog appears with token options
• Dialog shows existing public tokens (if any)
• After selection, preview URL is returned
• Server token NEVER appears anywhere - only the minimal-scope public token in URL

Screenshot locations:

• Elicitation dialog with options

• Preview URL result (only public token in URL)

• Token not in tool call log

Test Case 2: Subsequent Preview (Cached Token)

Steps:

1. After Test Case 1, call preview_style_tool again with different styleId
2. No accessToken provided

Expected:

• No elicitation dialog (token is cached)

• Preview URL generated immediately

• Same minimal-scope token used from cache

Test Case 3: Force New Token Selection

Steps:

1. Call preview_style_tool with useCustomToken: true
2. This time select "I have a token to provide"
3. Paste a valid public token

Expected:

• Elicitation dialog appears despite cache

• Token field accepts input
• New token replaces cached token

Test Case 4: Create Token with URL Restrictions

Steps:

1. Call preview_style_tool with new styleId, useCustomToken: true
2. Select "Create a new preview token with custom settings"
3. Enter token name: "Test Preview Token"
4. Enter URL restrictions: "https://example.com/*,https://test.com/*"

Expected:

• New token created via Mapbox API with minimal scopes

• Token includes URL restrictions for additional security

• Preview URL generated with new token

Test Case 5: Backward Compatibility

Steps:

1. Call preview_style_tool with both styleId AND accessToken

Expected:

• No elicitation dialog (token provided directly)

• Works exactly like before this PR
• Preview URL generated with provided token

Test Case 6: Elicitation Cancellation

Steps:

1. Call preview_style_tool without accessToken
2. When elicitation dialog appears, click "Cancel" or "Decline"

Expected:

• Tool returns error: "Token elicitation was cancelled or declined by user"

- No preview URL generated - Graceful error handling

Test Case 7: Works in Cursor

• Run Elicitation

- Get result

Test Case 8: Works in VS Code

• Run Elicitation

• Get result

Test Case 9: Works in Claude Desktop without support for Elicitation

• Run tool

• Ask to create a token for you

MCP Inspector Testing

To test in MCP Inspector:

npm run inspect:build

Then:

1. Connect to the server in MCP Inspector
2. Find preview_style_tool or style_comparison_tool in tools list
3. Call with: {"styleId": "cmi189f9600lj01sc7evj2vhs"} or {"before": "mapbox/streets-v12", "after": "mapbox/outdoors-v12"}
4. Observe elicitation dialog in Inspector UI
5. Test all three token options

Key Features

🔐 Security Improvements

• Principle of least privilege - Only minimal-scope read-only tokens (pk.*) appear in URLs
• Server token protection - Powerful server token (sk.*) with write permissions never exposed
• Reduced blast radius - Even if preview URL is shared, only read-only access to styles is exposed
• URL-restricted tokens - Users can create tokens that only work on specific domains
• Minimal scopes - Auto-created tokens only get styles:read, styles:tiles, fonts:read

🎯 User Experience

• Guided workflow - Three clear options for token management (provide, create, or auto-create)
• Session caching - Token only requested once per session
• Smart defaults - Auto-create option requires zero configuration
• No repeated prompts - Session storage remembers choice
• Backward compatible - Can still provide token directly via accessToken parameter
• Force re-selection - useCustomToken: true forces new token dialog
• Client capability checks - Gracefully falls back for clients without elicitation support

🛠️ Implementation Details

New Files:

• src/utils/tokenElicitation.ts - Elicitation dialog, session-token storage, and shared HTTP helpers (listPublicPreviewTokens, createPreviewToken, isTemporaryServerToken) used by both tools
• test/utils/tokenElicitation.test.ts - Unit tests for token storage, the shared HTTP helpers, and elicitation-dialog trimming (22 tests)

Modified Files:

• src/tools/preview-style-tool/PreviewStyleTool.ts - Integrated elicitation flow with capability checks; now takes httpRequest via constructor (see Update below)
• src/tools/preview-style-tool/PreviewStyleTool.input.schema.ts - Made accessToken optional, added useCustomToken
• src/tools/style-comparison-tool/StyleComparisonTool.ts - Integrated elicitation flow with capability checks; same constructor change
• src/tools/style-comparison-tool/StyleComparisonTool.schema.ts - Made accessToken optional, added useCustomToken
• src/tools/toolRegistry.ts, src/tools/index.ts - Updated to pass httpRequest into both tools' constructors
• test/tools/preview-style-tool/PreviewStyleTool.test.ts - Added elicitation behavior tests, including the tk.* dialog-trimming test (3 tests)
• test/tools/style-comparison-tool/StyleComparisonTool.test.ts - Added elicitation behavior tests, including the tk.* dialog-trimming test (3 tests)
• test/security/path-traversal.test.ts - Updated for the constructor signature change
• README.md, CHANGELOG.md - Updated documentation (security model, hosted-endpoint limitation)

Test Results

• ✅ All 651 tests pass (this branch was rebased onto current main, reworked to use the shared HttpPipeline instead of raw fetch, gained a real HTTP integration test, and fixed a cross-session elicitation hijack found during review; see Update and Critical Fix)
• ✅ Build succeeds with no type errors, lint clean
• ✅ Backward compatibility maintained
• ✅ Manual client testing (MCP Inspector, Cursor, VS Code, Claude Desktop) below is from the original implementation and has been re-run since the rebase/refactor — behavior for the "provide" and "backward compatible" paths is unchanged.

Breaking Changes

None for MCP tool callers - This is fully backward compatible over the wire:

• Existing code providing accessToken works exactly as before
• New behavior only activates when accessToken is omitted
• Clients without elicitation support work via capability checks

One for direct package consumers: PreviewStyleTool and StyleComparisonTool now both need httpRequest in their constructor (new PreviewStyleTool({ httpRequest })) instead of a no-arg constructor, to route the new token-listing/creation calls through the shared HttpPipeline rather than a bare fetch. The package's own pre-configured exports (import { previewStyle, styleComparison } from '@mapbox/mcp-devkit-server/tools') are updated accordingly and need no changes from consumers; only code that constructs these two classes directly is affected.

Security Model

What We Protect:

• ✅ Server token (sk.*) with write permissions never appears in chat history or URLs
• ✅ Only minimal-scope public tokens (pk.*) with read-only access can appear in URLs
• ✅ Enforces principle of least privilege automatically

Acceptable Security Trade-off:

• Public tokens (pk.*) with read-only scopes appear in preview URLs
• This is acceptable because:
  • They only grant read access to styles/tiles (no write permissions)
  • URL restrictions can further limit where tokens work
  • Much safer than exposing the server token with admin permissions

[Valiunia]

what happens if the client does not support selection dialog? Is that a possible scenario?

[mattpodwysocki]

Good catch — this was actually a real bug: if the client can't show the selection dialog, useCustomToken: true was forcing the same elicitation flow anyway, which then fails the capability check and returns an error — even when a perfectly good cached token already existed. Fixed in 848963c: useCustomToken now only bypasses the cache when the client actually supports elicitation; otherwise it silently falls back to the cached token (or the existing no-elicitation error if nothing is cached).

[Valiunia]

This looks dodgy - can we trust userName? maybe token signature is not valid, would getUserNameFromToken verify that? I doubt that it can, unless it's a network call

[mattpodwysocki]

Fair concern — getUserNameFromToken only base64-decodes the JWT payload, no signature verification. The username itself isn't a security boundary here (Mapbox's API re-authenticates via the token value regardless of what username we put in the request path), but I realized previewTokenStorage — new in this PR — was keying its in-memory cache off that unverified claim, which is a real (if narrow) risk for anyone running this behind a gateway that doesn't pre-verify bearers the way hosted-mcp-server does. Fixed in 848963c: the cache is now keyed by a sha256 hash of the actual token string (cacheKeyFor) instead of the decoded username, so two different presented tokens can never collide in the cache regardless of what they claim to be.

[Valiunia]

is this relevant anymore?

[mattpodwysocki]

Agreed, and I think you're pointing at something real beyond just staleness: this bug never shipped in any released version — it was found and fixed entirely within this unreleased PR. Calling it out as a standalone "### Security" entry (the format we'd normally use for "upgrade because a shipped version had a vulnerability") could misleadingly suggest a release was affected. Folded it into the elicitation feature bullet instead in c2f49b5 — no separate Security section.

[Valiunia]

Nit: I think instead of cached in memory per account for the session would be more accurate to say cached in memory per token ?

[mattpodwysocki]

You're right, that's more accurate — the cache key is a sha256 of the literal server access token (cacheKeyFor), not a resolved account identity, so "per token" describes it correctly and "per account" doesn't. Fixed in c2f49b5.

[Valiunia]

can we name getUserNameFromToken to getUntrustedUserNameFromToken or something? I fear if we can shoot ourselves in the foot in future by making assumptions and it slipping past peer review

[mattpodwysocki]

Agreed on the risk, but getUserNameFromToken is used in 12 files across the repo (jwtUtils.ts itself plus 10 other tools and their tests) — most of them untouched by this PR. Renaming it here would significantly widen this diff for something orthogonal to the elicitation work, and this PR is already large and waiting on approval. Strengthened the doc comment on the function in c2f49b5 to explicitly call out that it doesn't verify the signature and shouldn't be used for authorization decisions or sensitive cache keys (with a pointer to cacheKeyFor as the pattern to use instead when that matters). Happy to open a fast-follow PR for the actual rename across all call sites if you'd still like it done — let me know.