[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.
• README/CHANGELOG updated to document the above.
• All 644 tests pass (up from 529 - new coverage for the HttpPipeline refactor, the tk.* dialog-trimming behavior, and the HTTP integration 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.

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 644 tests pass (this branch was rebased onto current main, reworked to use the shared HttpPipeline instead of raw fetch, and gained a real HTTP integration test; see Update)
• ✅ 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