Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

feat(control-ui): surface MCP transport probe in remote wizard (C5)

Diego Zacarias7ea0bb1de53d
diff --git a/control-ui/app/globals.css b/control-ui/app/globals.css
index ec3c3e9ea..fe273f438 100644
--- a/control-ui/app/globals.css
+++ b/control-ui/app/globals.css
@@ -4703,6 +4703,11 @@ td.cu-registry-description {
color: var(--cu-text-soft);
}
+/* Canonical-URL suggestion action inside the dead-transport banner. */
+.cu-transport-suggestion {
+ margin-top: var(--cu-space-1);
+}
+
/* Catalog-attention banner (stale-but-referenced models) on /llm-models. */
.cu-model-attention__lede {
margin: 0 0 var(--cu-space-2);
diff --git a/control-ui/components/AddRemoteServerWizard/index.tsx b/control-ui/components/AddRemoteServerWizard/index.tsx
index 10c5fe174..b52e67880 100644
--- a/control-ui/components/AddRemoteServerWizard/index.tsx
+++ b/control-ui/components/AddRemoteServerWizard/index.tsx
@@ -10,6 +10,7 @@ import type { ContextResource } from '@lib/api'
import { contextResourceName } from '@lib/contextIdentity'
import {
buildRemoteInstallRequest,
+ describeTransportProbe,
discoverRemoteServer,
displayClientMode,
getRemoteServerNameError,
@@ -19,8 +20,9 @@ import {
mapRemoteInstallError,
requiresPreRegisteredCredentials,
shouldWarnNoRefresh,
+ transportBlocksContinue,
} from '@lib/remoteMcp'
-import type { RemoteDetected, RemoteGrantScope } from '@lib/remoteMcp.types'
+import type { RemoteDetected, RemoteGrantScope, RemoteTransportProbe } from '@lib/remoteMcp.types'
import {
GRANT_SCOPE_OPTIONS,
REGISTRATION_MODE_HINT,
@@ -54,6 +56,9 @@ export function AddRemoteServerWizard({
const [detecting, setDetecting] = useState(false)
const [discoverError, setDiscoverError] = useState('')
const [detected, setDetected] = useState<RemoteDetected | null>(null)
+ // MCP transport probe result for the current URL. A `dead` probe clears
+ // `detected` and holds the wizard on step 0; the others never block.
+ const [transport, setTransport] = useState<RemoteTransportProbe | null>(null)
// Step 1 — configuration
const [clientId, setClientId] = useState('')
@@ -91,6 +96,11 @@ export function AddRemoteServerWizard({
const needsCredentials = installMode ? requiresPreRegisteredCredentials(installMode) : false
const noRefresh = detected ? shouldWarnNoRefresh(detected) : false
+ const deadTransport = transport?.status === 'dead' ? transport : null
+ const suggestedBaseUrl = deadTransport?.suggestedBaseUrl
+ const inconclusiveTransport = transport?.status === 'inconclusive' ? transport : null
+ const aliveTransport = transport?.status === 'alive' ? transport : null
+
const credentialsComplete =
!needsCredentials || (clientId.trim().length > 0 && clientSecret.length > 0)
const step1Valid = Boolean(detected) && identifiersValid && credentialsComplete
@@ -112,15 +122,27 @@ export function AddRemoteServerWizard({
function resetDetection() {
setDetected(null)
+ setTransport(null)
setDiscoverError('')
}
async function runDetect() {
setDetecting(true)
setDiscoverError('')
+ setTransport(null)
try {
- const result = await discoverRemoteServer(trimmedBaseUrl)
- setDetected(result)
+ const { detected: nextDetected, transport: nextTransport } =
+ await discoverRemoteServer(trimmedBaseUrl)
+ if (transportBlocksContinue(nextTransport)) {
+ // Dead MCP transport: never install a URL the probe proved dead. Hold on
+ // step 0, surface the reason (and any canonical URL suggestion), and keep
+ // the primary action as "Detect" (no `detected` → no "Continue").
+ setDetected(null)
+ setTransport(nextTransport ?? null)
+ return
+ }
+ setDetected(nextDetected)
+ setTransport(nextTransport ?? null)
setStep(1)
} catch (e) {
if (isSilentApiError(e)) return
@@ -191,8 +213,8 @@ export function AddRemoteServerWizard({
monospace
onChange={event => {
setBaseUrl(event.target.value)
- // Editing the URL invalidates a prior detection.
- if (detected) resetDetection()
+ // Editing the URL invalidates a prior detection or transport probe.
+ if (detected || transport) resetDetection()
}}
placeholder="https://mcp.example.com/mcp"
disabled={detecting}
@@ -248,6 +270,26 @@ export function AddRemoteServerWizard({
{discoverError}
</div>
) : null}
+
+ {deadTransport ? (
+ <div className="cu-banner cu-banner--error" role="alert">
+ <div>{describeTransportProbe(deadTransport)}</div>
+ {suggestedBaseUrl ? (
+ <div className="cu-transport-suggestion">
+ <Button
+ onClick={() => {
+ setBaseUrl(suggestedBaseUrl)
+ resetDetection()
+ }}
+ size="sm"
+ variant="ghost"
+ >
+ Use {suggestedBaseUrl}
+ </Button>
+ </div>
+ ) : null}
+ </div>
+ ) : null}
</div>
) : null}
@@ -260,6 +302,12 @@ export function AddRemoteServerWizard({
</div>
) : null}
+ {inconclusiveTransport ? (
+ <div className="cu-banner cu-banner--warning" role="status">
+ {describeTransportProbe(inconclusiveTransport)}
+ </div>
+ ) : null}
+
<section className="cu-summary-list" aria-label="Detected OAuth configuration">
<div className="cu-summary-list__row">
<span>Registration mode</span>
@@ -277,6 +325,14 @@ export function AddRemoteServerWizard({
<span>Resource</span>
<strong>{detected.resource}</strong>
</div>
+ {aliveTransport ? (
+ <div className="cu-summary-list__row">
+ <span>MCP endpoint</span>
+ <strong>
+ {aliveTransport.challenge ? 'Reachable (sign-in required)' : 'Reachable'}
+ </strong>
+ </div>
+ ) : null}
<div className="cu-summary-list__row">
<span>Authorization endpoint</span>
<strong>{detected.endpoints.authorization}</strong>
@@ -403,6 +459,12 @@ export function AddRemoteServerWizard({
</div>
) : null}
+ {inconclusiveTransport ? (
+ <div className="cu-banner cu-banner--warning" role="status">
+ {describeTransportProbe(inconclusiveTransport)}
+ </div>
+ ) : null}
+
{installError ? (
<div className="cu-banner cu-banner--error" role="alert">
{installError}
diff --git a/control-ui/components/__tests__/AddRemoteServerWizard.test.tsx b/control-ui/components/__tests__/AddRemoteServerWizard.test.tsx
index 394fc425f..23f2639ec 100644
--- a/control-ui/components/__tests__/AddRemoteServerWizard.test.tsx
+++ b/control-ui/components/__tests__/AddRemoteServerWizard.test.tsx
@@ -1,11 +1,20 @@
-import type { ReactNode } from 'react'
import { afterEach, describe, expect, it, vi } from 'vitest'
import { cleanup, fireEvent, render as rtlRender, screen, waitFor } from '@testing-library/react'
import * as api from '../../lib/api'
import * as remoteMcp from '../../lib/remoteMcp'
-import type { RemoteDetected } from '../../lib/remoteMcp.types'
+import type {
+ DiscoverRemoteResponse,
+ RemoteDetected,
+ RemoteTransportProbe,
+} from '../../lib/remoteMcp.types'
import { buildContextResource } from '../../test/fixtures/contextResource'
-import { DCR_PUBLIC_DETECTED, NOTION_DETECTED } from '../../test/fixtures/remoteMcpDiscovery'
+import {
+ DCR_PUBLIC_DETECTED,
+ NOTION_DETECTED,
+ NOTION_TRANSPORT_ALIVE,
+ TRANSPORT_INCONCLUSIVE_TIMEOUT,
+ VERCEL_TRANSPORT_DEAD,
+} from '../../test/fixtures/remoteMcpDiscovery'
import { AddRemoteServerWizard } from '../AddRemoteServerWizard'
import { ToastProvider } from '../Toast'
@@ -33,6 +42,14 @@ const discoverMock = vi.mocked(remoteMcp.discoverRemoteServer)
const installMock = vi.mocked(remoteMcp.installRemoteServer)
const getContextsMock = vi.mocked(api.getContexts)
+/** The discover response shape control-api returns: `detected` plus the probe. */
+function discovered(
+ detected: RemoteDetected,
+ transport?: RemoteTransportProbe
+): DiscoverRemoteResponse {
+ return { detected, transport }
+}
+
afterEach(() => {
cleanup()
vi.clearAllMocks()
@@ -75,7 +92,7 @@ function clickDetect() {
describe('AddRemoteServerWizard', () => {
it('detects a server and advances to the configuration step showing the detected values', async () => {
- discoverMock.mockResolvedValue(NOTION_DETECTED)
+ discoverMock.mockResolvedValue(discovered(NOTION_DETECTED))
renderWizard()
await fillIdentity()
clickDetect()
@@ -90,7 +107,7 @@ describe('AddRemoteServerWizard', () => {
})
it('D-4: editing the URL after a detect invalidates it and blocks proceeding until re-detect', async () => {
- discoverMock.mockResolvedValue(NOTION_DETECTED)
+ discoverMock.mockResolvedValue(discovered(NOTION_DETECTED))
renderWizard()
await fillIdentity()
clickDetect()
@@ -112,7 +129,7 @@ describe('AddRemoteServerWizard', () => {
it('shows client credential fields only for the manual (pre-registered) mode', async () => {
// manual has no real probed pilot; this is UI state, not a producer fixture.
const manualDetected: RemoteDetected = { ...NOTION_DETECTED, registrationMode: 'manual' }
- discoverMock.mockResolvedValue(manualDetected)
+ discoverMock.mockResolvedValue(discovered(manualDetected))
renderWizard()
await fillIdentity()
clickDetect()
@@ -124,7 +141,7 @@ describe('AddRemoteServerWizard', () => {
})
it('does not show credential fields for cimd or dcr modes', async () => {
- discoverMock.mockResolvedValue(NOTION_DETECTED) // cimd
+ discoverMock.mockResolvedValue(discovered(NOTION_DETECTED)) // cimd
renderWizard()
await fillIdentity()
clickDetect()
@@ -132,7 +149,7 @@ describe('AddRemoteServerWizard', () => {
expect(screen.queryByLabelText(/Client ID/)).not.toBeInTheDocument()
cleanup()
- discoverMock.mockResolvedValue(DCR_PUBLIC_DETECTED) // dcr
+ discoverMock.mockResolvedValue(discovered(DCR_PUBLIC_DETECTED)) // dcr
renderWizard()
await fillIdentity()
clickDetect()
@@ -145,14 +162,14 @@ describe('AddRemoteServerWizard', () => {
...NOTION_DETECTED,
quirks: { bearerInBody: false, supportsRefresh: false },
}
- discoverMock.mockResolvedValue(noRefresh)
+ discoverMock.mockResolvedValue(discovered(noRefresh))
renderWizard()
await fillIdentity()
clickDetect()
expect(await screen.findByText(/does not support token refresh/i)).toBeInTheDocument()
cleanup()
- discoverMock.mockResolvedValue(NOTION_DETECTED) // supportsRefresh true
+ discoverMock.mockResolvedValue(discovered(NOTION_DETECTED)) // supportsRefresh true
renderWizard()
await fillIdentity()
clickDetect()
@@ -161,7 +178,7 @@ describe('AddRemoteServerWizard', () => {
})
it('installs successfully: sends the request, fires onInstalled, and toasts', async () => {
- discoverMock.mockResolvedValue(NOTION_DETECTED)
+ discoverMock.mockResolvedValue(discovered(NOTION_DETECTED))
installMock.mockResolvedValue({
serverName: 'notion-remote',
namespace: 'mcp-server',
@@ -193,7 +210,7 @@ describe('AddRemoteServerWizard', () => {
})
it('shows a mapped install error inline', async () => {
- discoverMock.mockResolvedValue(NOTION_DETECTED)
+ discoverMock.mockResolvedValue(discovered(NOTION_DETECTED))
installMock.mockRejectedValue(
Object.assign(new Error('503'), { code: 'callback_base_url_unconfigured', body: {} })
)
@@ -208,4 +225,95 @@ describe('AddRemoteServerWizard', () => {
expect(await screen.findByText(/callback url is not configured/i)).toBeInTheDocument()
expect(onInstalled).not.toHaveBeenCalled()
})
+
+ // ── C5 transport probe ──────────────────────────────────────────────────────
+
+ it('C5 transport dead: holds on step 0, alerts, offers the suggestion, and never shows Continue', async () => {
+ // Repro for issue 26-09-25: OAuth valid but MCP transport dead at the typed
+ // path. Against the parent head the wizard advances to step 1 instead.
+ discoverMock.mockResolvedValue(discovered(NOTION_DETECTED, VERCEL_TRANSPORT_DEAD))
+ renderWizard()
+ await fillIdentity('https://mcp.vercel.com/mcp', 'vercel-mcp')
+ clickDetect()
+
+ // A dead probe surfaces an alert and holds step 0 (no configuration values).
+ const alert = await screen.findByRole('alert')
+ expect(alert).toHaveTextContent('https://mcp.vercel.com/')
+ expect(screen.queryByText('https://mcp.notion.com/authorize')).not.toBeInTheDocument()
+
+ // Never a "Continue" — the primary action stays "Detect".
+ expect(screen.queryByRole('button', { name: 'Continue' })).not.toBeInTheDocument()
+ expect(screen.getByRole('button', { name: 'Detect' })).toBeInTheDocument()
+ // The Configure rail step is not selectable.
+ expect(screen.getByRole('button', { name: /Configure/ })).toBeDisabled()
+
+ // Applying the suggestion loads it into the input and re-enables Detect.
+ fireEvent.click(screen.getByRole('button', { name: 'Use https://mcp.vercel.com/' }))
+ expect(screen.getByPlaceholderText('https://mcp.example.com/mcp')).toHaveValue(
+ 'https://mcp.vercel.com/'
+ )
+ expect(screen.queryByRole('alert')).not.toBeInTheDocument()
+ expect(screen.getByRole('button', { name: 'Detect' })).toBeEnabled()
+ })
+
+ it('C5 transport inconclusive: advances and shows a status banner on the config and confirm steps', async () => {
+ discoverMock.mockResolvedValue(discovered(NOTION_DETECTED, TRANSPORT_INCONCLUSIVE_TIMEOUT))
+ renderWizard()
+ await fillIdentity()
+ clickDetect()
+
+ // Advances to configuration with a non-blocking status banner.
+ await screen.findByText('https://mcp.notion.com/authorize')
+ expect(screen.getByText(/Couldn't confirm the MCP endpoint/i)).toBeInTheDocument()
+ expect(
+ screen.getByText(/Couldn't confirm the MCP endpoint/i).closest('[role="status"]')
+ ).not.toBeNull()
+
+ // The banner persists on the confirm step.
+ fireEvent.click(screen.getByRole('button', { name: 'Continue' }))
+ await screen.findByRole('button', { name: 'Install remote server' })
+ expect(screen.getByText(/Couldn't confirm the MCP endpoint/i)).toBeInTheDocument()
+ })
+
+ it('C5 transport alive: advances with no transport banner and shows the reachable summary row', async () => {
+ discoverMock.mockResolvedValue(discovered(NOTION_DETECTED, NOTION_TRANSPORT_ALIVE))
+ renderWizard()
+ await fillIdentity()
+ clickDetect()
+
+ await screen.findByText('https://mcp.notion.com/authorize')
+ // A challenge probe reports the endpoint reachable (sign-in required).
+ expect(screen.getByText('Reachable (sign-in required)')).toBeInTheDocument()
+ // No transport warning/error banner (Notion also supports refresh → no status).
+ expect(screen.queryByRole('alert')).not.toBeInTheDocument()
+ expect(screen.queryByRole('status')).not.toBeInTheDocument()
+ })
+
+ it('C5 install transport_unreachable: shows the mapped error inline with the suggested URL', async () => {
+ discoverMock.mockResolvedValue(discovered(NOTION_DETECTED, NOTION_TRANSPORT_ALIVE))
+ installMock.mockRejectedValue(
+ Object.assign(new Error('400'), {
+ code: 'transport_unreachable',
+ body: {
+ error: 'transport_unreachable',
+ detail: {
+ probedUrl: 'https://mcp.vercel.com/mcp',
+ httpStatus: 404,
+ suggestedBaseUrl: 'https://mcp.vercel.com/',
+ },
+ },
+ })
+ )
+ const { onInstalled } = renderWizard()
+ await fillIdentity()
+ clickDetect()
+ await screen.findByText('https://mcp.notion.com/authorize')
+
+ fireEvent.click(screen.getByRole('button', { name: 'Continue' }))
+ fireEvent.click(await screen.findByRole('button', { name: 'Install remote server' }))
+
+ expect(await screen.findByText(/isn't reachable at that URL/i)).toBeInTheDocument()
+ expect(screen.getByText(/https:\/\/mcp\.vercel\.com\//)).toBeInTheDocument()
+ expect(onInstalled).not.toHaveBeenCalled()
+ })
})
diff --git a/control-ui/lib/__tests__/remoteMcp.test.ts b/control-ui/lib/__tests__/remoteMcp.test.ts
index 97a624830..49e4ebd76 100644
--- a/control-ui/lib/__tests__/remoteMcp.test.ts
+++ b/control-ui/lib/__tests__/remoteMcp.test.ts
@@ -3,10 +3,14 @@ import {
DCR_CONFIDENTIAL_DETECTED,
DCR_PUBLIC_DETECTED,
NOTION_DETECTED,
+ NOTION_TRANSPORT_ALIVE,
+ TRANSPORT_INCONCLUSIVE_TIMEOUT,
+ VERCEL_TRANSPORT_DEAD,
} from '../../test/fixtures/remoteMcpDiscovery'
import {
buildRemoteInstallRequest,
describeDiscoveryError,
+ describeTransportProbe,
displayClientMode,
getRemoteServerNameError,
installModeForRegistration,
@@ -14,8 +18,9 @@ import {
mapRemoteInstallError,
requiresPreRegisteredCredentials,
shouldWarnNoRefresh,
+ transportBlocksContinue,
} from '../remoteMcp'
-import type { RemoteDetected } from '../remoteMcp.types'
+import type { RemoteDetected, RemoteTransportProbe } from '../remoteMcp.types'
describe('installModeForRegistration (D-3/D-7)', () => {
it('maps each registration mode to its install mode', () => {
@@ -221,4 +226,114 @@ describe('mapRemoteInstallError', () => {
})
expect(mapRemoteInstallError(err)).toContain('context "research" not found')
})
+
+ it('maps transport_unreachable with the suggested canonical URL', () => {
+ const err = Object.assign(new Error('400'), {
+ status: 400,
+ code: 'transport_unreachable',
+ body: {
+ error: 'transport_unreachable',
+ detail: {
+ probedUrl: 'https://mcp.vercel.com/mcp',
+ httpStatus: 404,
+ suggestedBaseUrl: 'https://mcp.vercel.com/',
+ },
+ },
+ })
+ const copy = mapRemoteInstallError(err)
+ expect(copy).toContain('https://mcp.vercel.com/')
+ expect(copy).toContain('404')
+ })
+
+ it('maps transport_unreachable without a suggestion', () => {
+ const err = Object.assign(new Error('400'), {
+ code: 'transport_unreachable',
+ body: {
+ error: 'transport_unreachable',
+ detail: { probedUrl: 'https://mcp.example.com/mcp', httpStatus: 405 },
+ },
+ })
+ const copy = mapRemoteInstallError(err)
+ expect(copy).toMatch(/isn't reachable/i)
+ expect(copy).toContain('405')
+ expect(copy).not.toContain('looks like')
+ })
+})
+
+describe('transportBlocksContinue', () => {
+ it('blocks only on a proven dead transport', () => {
+ expect(transportBlocksContinue(VERCEL_TRANSPORT_DEAD)).toBe(true)
+ expect(transportBlocksContinue(NOTION_TRANSPORT_ALIVE)).toBe(false)
+ expect(transportBlocksContinue(TRANSPORT_INCONCLUSIVE_TIMEOUT)).toBe(false)
+ // An absent probe (older control-api) never blocks.
+ expect(transportBlocksContinue(undefined)).toBe(false)
+ })
+})
+
+describe('describeTransportProbe', () => {
+ it('does not describe an alive transport (the summary row handles it)', () => {
+ expect(describeTransportProbe(NOTION_TRANSPORT_ALIVE)).toBe('')
+ })
+
+ it('describes a dead transport with its suggested canonical URL', () => {
+ const copy = describeTransportProbe(VERCEL_TRANSPORT_DEAD)
+ expect(copy).toContain('404')
+ expect(copy).toContain('https://mcp.vercel.com/')
+ expect(copy).toMatch(/looks like/i)
+ })
+
+ it('describes a dead transport without a suggestion differently', () => {
+ const dead: RemoteTransportProbe = {
+ status: 'dead',
+ probedUrl: 'https://mcp.example.com/mcp',
+ httpStatus: 405,
+ }
+ const copy = describeTransportProbe(dead)
+ expect(copy).toContain('405')
+ expect(copy).toMatch(/double-check the url path/i)
+ expect(copy).not.toMatch(/looks like/i)
+ })
+
+ it('gives a distinct, non-blocking message per inconclusive reason', () => {
+ const timeout = describeTransportProbe(TRANSPORT_INCONCLUSIVE_TIMEOUT)
+ expect(timeout).toMatch(/timed out/i)
+ expect(timeout).toMatch(/can still install/i)
+
+ const redirect = describeTransportProbe({
+ status: 'inconclusive',
+ probedUrl: 'https://mcp.example.com/mcp',
+ reason: 'redirect',
+ detail: 'redirected',
+ })
+ expect(redirect).toMatch(/redirect/i)
+
+ const unexpected = describeTransportProbe({
+ status: 'inconclusive',
+ probedUrl: 'https://mcp.example.com/mcp',
+ reason: 'unexpected_status',
+ httpStatus: 500,
+ detail: 'unexpected status 500',
+ })
+ expect(unexpected).toContain('500')
+
+ // Every reason must return distinct copy, not the same fallback.
+ const messages = (
+ [
+ 'timeout',
+ 'transport_failed',
+ 'redirect',
+ 'unexpected_status',
+ 'content_encoding_rejected',
+ 'kernel_rejected',
+ ] as const
+ ).map(reason =>
+ describeTransportProbe({
+ status: 'inconclusive',
+ probedUrl: 'https://mcp.example.com/mcp',
+ reason,
+ detail: reason,
+ })
+ )
+ expect(new Set(messages).size).toBe(messages.length)
+ })
})
diff --git a/control-ui/lib/remoteMcp.ts b/control-ui/lib/remoteMcp.ts
index b5e4e0924..a024294bb 100644
--- a/control-ui/lib/remoteMcp.ts
+++ b/control-ui/lib/remoteMcp.ts
@@ -6,11 +6,13 @@ import type {
DiscoverRemoteResponse,
InstallRemoteRequest,
InstallRemoteResponse,
+ InstallTransportUnreachableDetail,
RemoteClientMode,
RemoteDetected,
RemoteDiscoveryErrorKind,
RemoteInstallMode,
RemoteRegistrationMode,
+ RemoteTransportProbe,
} from './remoteMcp.types'
/** Real admin prefix for the remote MCP-OAuth routes (control-api). */
@@ -19,14 +21,14 @@ export const REMOTE_MCP_BASE = '/api/v1/admin/mcp-servers/remote'
// ── API client (matches lib/api.ts; apiSend attaches the admin bearer) ───────
/**
- * Dry-run discovery for `baseUrl`. Resolves to the `detected` prefill or throws
+ * Dry-run discovery for `baseUrl`. Resolves to the full discover response — the
+ * `detected` OAuth prefill plus the optional MCP `transport` probe — or throws
* the `apiSend` error (whose `.code`/`.body` carry the discovery-error detail).
*/
-export async function discoverRemoteServer(baseUrl: string): Promise<RemoteDetected> {
- const res = (await apiSend('POST', `${REMOTE_MCP_BASE}/discover`, {
+export async function discoverRemoteServer(baseUrl: string): Promise<DiscoverRemoteResponse> {
+ return (await apiSend('POST', `${REMOTE_MCP_BASE}/discover`, {
baseUrl,
})) as DiscoverRemoteResponse
- return res.detected
}
/** Transactional install saga. Resolves to the names-only summary (201). */
@@ -75,6 +77,49 @@ export function shouldWarnNoRefresh(detected: Pick<RemoteDetected, 'quirks'>): b
return detected.quirks.supportsRefresh === false
}
+/**
+ * Whether the MCP transport probe forbids advancing/installing. Only a proven
+ * `dead` path (404/405) blocks; `inconclusive` and `alive` never do, and an
+ * absent probe (older control-api) never blocks (D3 fail-open).
+ */
+export function transportBlocksContinue(transport?: RemoteTransportProbe): boolean {
+ return transport?.status === 'dead'
+}
+
+/**
+ * Operator-facing copy for a transport probe. `dead` explains the path serves no
+ * MCP (and names the canonical URL when one was verified); `inconclusive`
+ * reassures that install can still proceed. `alive` has no banner — the confirm
+ * step shows a reachable summary row instead — so it maps to an empty string.
+ */
+export function describeTransportProbe(transport: RemoteTransportProbe): string {
+ switch (transport.status) {
+ case 'alive':
+ return ''
+ case 'dead':
+ return transport.suggestedBaseUrl
+ ? `OAuth works here, but this URL's MCP endpoint returned ${transport.httpStatus} — nothing is serving MCP at that path. This server's MCP endpoint looks like ${transport.suggestedBaseUrl}.`
+ : `OAuth works here, but this URL's MCP endpoint returned ${transport.httpStatus} — nothing is serving MCP at that path. Double-check the URL path.`
+ case 'inconclusive':
+ switch (transport.reason) {
+ case 'timeout':
+ return "Couldn't confirm the MCP endpoint — the probe timed out. You can still install; the connector will verify it on first use."
+ case 'transport_failed':
+ return "Couldn't reach the MCP endpoint to confirm it. You can still install; the connector will verify it on first use."
+ case 'redirect':
+ return "The MCP endpoint redirected the probe, so it couldn't be confirmed here. You can still install; the connector follows redirects at runtime."
+ case 'unexpected_status':
+ return transport.httpStatus
+ ? `The MCP endpoint returned an unexpected status (${transport.httpStatus}), so it couldn't be confirmed. You can still install.`
+ : "The MCP endpoint returned an unexpected response, so it couldn't be confirmed. You can still install."
+ case 'content_encoding_rejected':
+ return "The MCP endpoint's response encoding couldn't be inspected, so it couldn't be confirmed. You can still install."
+ case 'kernel_rejected':
+ return "The MCP endpoint couldn't be probed under the security policy. You can still install."
+ }
+ }
+}
+
/**
* The client mode to display on the confirm step. Pre-registered is always
* confidential; CIMD is always public; DCR carries the AS-derived mode in its
@@ -198,6 +243,19 @@ export function mapRemoteInstallError(error: unknown): string {
return describeDiscoveryError(discoveryDetailKind(body))
case 'invalid_request':
return 'The install request was rejected as invalid. Reload the page and try again.'
+ case 'transport_unreachable': {
+ // The MCP transport probe found the typed path dead before any write.
+ const detail =
+ body?.detail && typeof body.detail === 'object'
+ ? (body.detail as Partial<InstallTransportUnreachableDetail>)
+ : undefined
+ const suggested =
+ detail && typeof detail.suggestedBaseUrl === 'string' ? detail.suggestedBaseUrl : ''
+ const httpStatus = detail && typeof detail.httpStatus === 'number' ? detail.httpStatus : 404
+ return suggested
+ ? `This server's MCP endpoint isn't reachable at that URL (HTTP ${httpStatus}). Its MCP endpoint looks like ${suggested} — go back and detect that URL instead.`
+ : `This server's MCP endpoint isn't reachable at that URL (HTTP ${httpStatus}). Go back and check the URL.`
+ }
default:
break
}
diff --git a/control-ui/lib/remoteMcp.types.ts b/control-ui/lib/remoteMcp.types.ts
index 9fac1d02b..6f55b095b 100644
--- a/control-ui/lib/remoteMcp.types.ts
+++ b/control-ui/lib/remoteMcp.types.ts
@@ -59,8 +59,44 @@ export interface DiscoverRemoteRequest {
baseUrl: string
}
+/**
+ * The `reason` an MCP transport probe could not be classified as alive or dead.
+ * Mirrors control-api's `mcpTransportProbe.ts` inconclusive reasons. None of
+ * these block Detect or Install — they only surface a warning (D3 fail-open).
+ */
+export type RemoteTransportInconclusiveReason =
+ | 'timeout'
+ | 'transport_failed'
+ | 'redirect'
+ | 'unexpected_status'
+ | 'content_encoding_rejected'
+ | 'kernel_rejected'
+
+/**
+ * Result of control-api's MCP transport probe: a token-less `initialize` POST
+ * against the typed URL. `alive` = the path speaks MCP (200/202, or a spec
+ * 401/403 challenge); `dead` = 404/405, the path serves no MCP (only this blocks
+ * Continue/Install) and may carry a verified canonical `suggestedBaseUrl`;
+ * `inconclusive` = anything the probe cannot prove either way (never blocks).
+ */
+export type RemoteTransportProbe =
+ | { status: 'alive'; probedUrl: string; httpStatus: number; challenge: boolean }
+ | { status: 'dead'; probedUrl: string; httpStatus: 404 | 405; suggestedBaseUrl?: string }
+ | {
+ status: 'inconclusive'
+ probedUrl: string
+ reason: RemoteTransportInconclusiveReason
+ httpStatus?: number
+ detail: string
+ }
+
export interface DiscoverRemoteResponse {
detected: RemoteDetected
+ /**
+ * The MCP transport probe result. Optional so the wizard tolerates a
+ * control-api older than the probe (a missing `transport` never blocks).
+ */
+ transport?: RemoteTransportProbe
}
export interface InstallRemoteRequest {
@@ -85,6 +121,18 @@ export interface InstallRemoteResponse {
clientSecretName?: string
}
+/**
+ * Detail of the new install-time `400 { error: 'transport_unreachable' }`,
+ * emitted before any write when the MCP transport probe finds the typed path
+ * dead (404/405). `suggestedBaseUrl` is present only when the backend resolved a
+ * reachable canonical URL; `mapRemoteInstallError` surfaces it in the copy.
+ */
+export interface InstallTransportUnreachableDetail {
+ probedUrl: string
+ httpStatus: number
+ suggestedBaseUrl?: string
+}
+
/**
* The typed error union returned by `/discover` (and re-run at install) under
* `{ error: 'discovery_failed', detail }`. Mirrors control-api's `DiscoveryError`
diff --git a/control-ui/package-lock.json b/control-ui/package-lock.json
index 6a11d5f01..a7466dcb2 100644
--- a/control-ui/package-lock.json
+++ b/control-ui/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-ui",
- "version": "0.1.654",
+ "version": "0.1.655",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-ui",
- "version": "0.1.654",
+ "version": "0.1.655",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/frontend-components": "file:../packages/frontend-components",
diff --git a/control-ui/package.json b/control-ui/package.json
index 956a113f2..349558be4 100644
--- a/control-ui/package.json
+++ b/control-ui/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-ui",
- "version": "0.1.654",
+ "version": "0.1.655",
"private": true,
"scripts": {
"dev": "NEXT_IGNORE_INCORRECT_LOCKFILE=1 next dev",
diff --git a/control-ui/test/fixtures/__tests__/remoteMcpDiscovery.contract.test.ts b/control-ui/test/fixtures/__tests__/remoteMcpDiscovery.contract.test.ts
index fa8115d25..a564d5f98 100644
--- a/control-ui/test/fixtures/__tests__/remoteMcpDiscovery.contract.test.ts
+++ b/control-ui/test/fixtures/__tests__/remoteMcpDiscovery.contract.test.ts
@@ -1,5 +1,5 @@
import { describe, expect, it } from 'vitest'
-import type { RemoteDetected } from '../../../lib/remoteMcp.types'
+import type { RemoteDetected, RemoteTransportProbe } from '../../../lib/remoteMcp.types'
import {
CANVA_AS_JSON,
CANVA_DETECTED,
@@ -8,15 +8,22 @@ import {
DCR_CONFIDENTIAL_DETECTED,
DCR_PUBLIC_AS_JSON,
DCR_PUBLIC_DETECTED,
+ type InitializeProbeObservation,
LINEAR_AS_JSON,
LINEAR_DETECTED,
LINEAR_PRM_JSON,
NOTION_AS_JSON,
NOTION_DETECTED,
+ NOTION_MCP_INITIALIZE,
NOTION_PRM_JSON,
+ NOTION_TRANSPORT_ALIVE,
SENTRY_AS_JSON,
SENTRY_DETECTED,
SENTRY_PRM_JSON,
+ VERCEL_MCP_INITIALIZE,
+ VERCEL_ROOT_INITIALIZE,
+ VERCEL_ROOT_PRM_JSON,
+ VERCEL_TRANSPORT_DEAD,
} from '../remoteMcpDiscovery'
/**
@@ -116,3 +123,90 @@ describe('remote MCP `detected` fixtures match the real probe bytes', () => {
expect(CANVA_DETECTED.issForCallback).toBeUndefined()
})
})
+
+/**
+ * Reproduces the producer's MCP transport classifier + canonical-URL suggestion
+ * (control-api `mcpTransportProbe.ts`, decision table in the mini-spec) from the
+ * observed `initialize` statuses and the real root-PRM bytes, and asserts each
+ * hand-derived RemoteTransportProbe fixture equals it. A drifted fixture fails.
+ *
+ * This is a local re-projection: control-ui cannot import control-api. The real
+ * producer's output is anchored in control-api `test/routes.adminRemoteMcp.test.ts`
+ * (it asserts these same literal shapes). If the classifier drifts, that test is
+ * the one that catches it — treat this projection as a mirror, not the authority.
+ */
+function classifyInitialize(obs: InitializeProbeObservation): 'alive' | 'dead' | 'inconclusive' {
+ const { httpStatus } = obs
+ if (httpStatus === 200 || httpStatus === 202 || httpStatus === 401 || httpStatus === 403) {
+ return 'alive'
+ }
+ if (httpStatus === 404 || httpStatus === 405) return 'dead'
+ return 'inconclusive'
+}
+
+/** Trailing-slash-insensitive path, so `/mcp` differs from `/` but not from `/mcp/`. */
+function trimmedPath(url: string): string {
+ const { pathname } = new URL(url)
+ return pathname.length > 1 && pathname.endsWith('/') ? pathname.slice(0, -1) : pathname
+}
+
+function projectTransport(
+ typed: InitializeProbeObservation,
+ rootPrmJson?: string,
+ candidate?: InitializeProbeObservation
+): RemoteTransportProbe {
+ const verdict = classifyInitialize(typed)
+ if (verdict === 'alive') {
+ return {
+ status: 'alive',
+ probedUrl: typed.url,
+ httpStatus: typed.httpStatus,
+ challenge: typed.wwwAuthenticate,
+ }
+ }
+ if (verdict === 'inconclusive') {
+ return {
+ status: 'inconclusive',
+ probedUrl: typed.url,
+ reason: 'unexpected_status',
+ httpStatus: typed.httpStatus,
+ detail: `unexpected status ${typed.httpStatus}`,
+ }
+ }
+
+ // dead — resolve a canonical suggestion (only when the typed path is not root
+ // and a same-origin, different-path root `resource` probes alive).
+ let suggestedBaseUrl: string | undefined
+ const typedUrl = new URL(typed.url)
+ if (typedUrl.pathname !== '/' && rootPrmJson && candidate) {
+ const prm = JSON.parse(rootPrmJson) as { resource?: unknown }
+ const resource = typeof prm.resource === 'string' ? prm.resource : undefined
+ const candidateUrl =
+ resource &&
+ new URL(resource).origin === typedUrl.origin &&
+ trimmedPath(resource) !== trimmedPath(typed.url)
+ ? resource
+ : `${typedUrl.origin}/`
+ if (candidateUrl === candidate.url && classifyInitialize(candidate) === 'alive') {
+ suggestedBaseUrl = candidate.url
+ }
+ }
+ return {
+ status: 'dead',
+ probedUrl: typed.url,
+ httpStatus: typed.httpStatus as 404 | 405,
+ ...(suggestedBaseUrl ? { suggestedBaseUrl } : {}),
+ }
+}
+
+describe('remote MCP `transport` fixtures match the real probe outputs', () => {
+ it('vercel /mcp: 404 → dead, with the root resource as the verified suggestion', () => {
+ expect(VERCEL_TRANSPORT_DEAD).toEqual(
+ projectTransport(VERCEL_MCP_INITIALIZE, VERCEL_ROOT_PRM_JSON, VERCEL_ROOT_INITIALIZE)
+ )
+ })
+
+ it('notion /mcp: 401 challenge → alive (the case the issue must not break)', () => {
+ expect(NOTION_TRANSPORT_ALIVE).toEqual(projectTransport(NOTION_MCP_INITIALIZE))
+ })
+})
diff --git a/control-ui/test/fixtures/remoteMcpDiscovery.ts b/control-ui/test/fixtures/remoteMcpDiscovery.ts
index a458bd318..0d7670baa 100644
--- a/control-ui/test/fixtures/remoteMcpDiscovery.ts
+++ b/control-ui/test/fixtures/remoteMcpDiscovery.ts
@@ -14,7 +14,7 @@
* This mirrors the repo's existing producer-fixture pattern (test/fixtures/
* contextResource.ts + its *.contract.test.ts).
*/
-import type { RemoteDetected } from '../../lib/remoteMcp.types'
+import type { RemoteDetected, RemoteTransportProbe } from '../../lib/remoteMcp.types'
// ─── Verbatim real probe bytes (control-api T1 fixtures, 2026-09-20) ──────────
@@ -163,3 +163,72 @@ export const DCR_CONFIDENTIAL_DETECTED: RemoteDetected = {
scopes: ['default'],
quirks: { bearerInBody: false, supportsRefresh: true },
}
+
+// ─── MCP transport probe fixtures (live probes 2026-09-25) ────────────────────
+//
+// control-ui cannot run control-api's `mcpTransportProbe.ts`, so — as with the
+// `detected` fixtures above — the RemoteTransportProbe values below are DERIVED
+// FROM THE REAL PROBE OUTPUTS: the verbatim root-PRM bytes plus the observed
+// `initialize` HTTP statuses. The colocated contract test re-applies the
+// producer's decision table + canonical-URL suggestion rule to those raw inputs
+// and asserts each fixture equals the projection, so a drifted value fails.
+
+/** Vercel serves OAuth PRM per-path; the root `resource` is the canonical URL. */
+export const VERCEL_ROOT_PRM_JSON =
+ '{"resource":"https://mcp.vercel.com/","authorization_servers":["https://vercel.com"],"scopes_supported":["openid"],"resource_name":"Vercel MCP"}'
+export const VERCEL_MCP_PRM_JSON =
+ '{"resource":"https://mcp.vercel.com/mcp","authorization_servers":["https://vercel.com"],"scopes_supported":["openid"],"resource_name":"Vercel MCP"}'
+
+/**
+ * Observed token-less `initialize` POST responses (status + www-authenticate
+ * presence). These are the producer's raw probe outputs; the contract test's
+ * `projectTransport` re-derives each RemoteTransportProbe from them.
+ */
+export interface InitializeProbeObservation {
+ url: string
+ httpStatus: number
+ wwwAuthenticate: boolean
+}
+
+/** Vercel `/mcp`: 404 (Next.js 404 page) — the MCP transport is not there. */
+export const VERCEL_MCP_INITIALIZE: InitializeProbeObservation = {
+ url: 'https://mcp.vercel.com/mcp',
+ httpStatus: 404,
+ wwwAuthenticate: false,
+}
+/** Vercel root `/`: 200 text/event-stream — the real MCP transport. */
+export const VERCEL_ROOT_INITIALIZE: InitializeProbeObservation = {
+ url: 'https://mcp.vercel.com/',
+ httpStatus: 200,
+ wwwAuthenticate: false,
+}
+/** Notion `/mcp`: 401 with a Bearer challenge — a live transport requiring auth. */
+export const NOTION_MCP_INITIALIZE: InitializeProbeObservation = {
+ url: 'https://mcp.notion.com/mcp',
+ httpStatus: 401,
+ wwwAuthenticate: true,
+}
+
+/** Vercel `/mcp` dead, with the verified root as the canonical suggestion. */
+export const VERCEL_TRANSPORT_DEAD: RemoteTransportProbe = {
+ status: 'dead',
+ probedUrl: 'https://mcp.vercel.com/mcp',
+ httpStatus: 404,
+ suggestedBaseUrl: 'https://mcp.vercel.com/',
+}
+
+/** Notion `/mcp` alive: a spec 401 challenge is a live transport that needs auth. */
+export const NOTION_TRANSPORT_ALIVE: RemoteTransportProbe = {
+ status: 'alive',
+ probedUrl: 'https://mcp.notion.com/mcp',
+ httpStatus: 401,
+ challenge: true,
+}
+
+/** A transient probe timeout — inconclusive, never blocks (fail-open). */
+export const TRANSPORT_INCONCLUSIVE_TIMEOUT: RemoteTransportProbe = {
+ status: 'inconclusive',
+ probedUrl: 'https://mcp.example.com/mcp',
+ reason: 'timeout',
+ detail: 'initialize probe timed out',
+}