A desktop coding agent with free access to frontier models.
TypeScript
import { and, eq, isNull } from "@omnirush-ee/den-db/drizzle"
import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js"
import { StreamableHTTPError } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
import {
OMNIRUSH_CLOUD_MCP_CONNECTION_ACTION_KIND,
OMNIRUSH_CLOUD_MCP_CONNECTION_ACTION_SOURCE,
OMNIRUSH_CLOUD_MCP_CONNECTION_ACTION_VERSION,
} from "@omnirush/types/den/mcp-connection-action"
import { normalizeDenTypeId, type DenTypeId } from "@omnirush-ee/utils/typeid"
import {
getExternalMcpConnection,
listUsableExternalMcpConnections,
memberCanUseExternalMcpConnection,
type ExternalMcpConnectionRow,
} from "../capability-sources/external-mcp-connections.js"
import { callExternalMcpTool, listExternalMcpTools } from "../capability-sources/external-mcp-client-runtime.js"
import {
EXTERNAL_MCP_TOOL_LIFECYCLE_TIMEOUT_MS,
createExternalMcpLifecycleDeadline,
type ExternalMcpLifecycleDeadline,
} from "../capability-sources/external-mcp-client.js"
import {
ExternalMcpDiagnosticError,
externalMcpDiagnosticForLog,
safeExternalMcpEndpointForLog,
type ExternalMcpDiagnostic,
} from "../capability-sources/external-mcp-diagnostics.js"
import { getConnectedAccount } from "../capability-sources/oauth-credentials.js"
import {
evaluateToolPolicy,
isToolDisabled,
} from "../capability-sources/external-mcp-tool-policy.js"
import { cache } from "../cache.js"
import { db } from "../db.js"
import { listTeamsForMember } from "../orgs.js"
import { omnirushOrganizationConnectionsUrl, omnirushYourConnectionsUrl } from "./connection-navigation.js"
import {
externalMcpToolSchemaDigest,
validateExternalMcpToolArguments,
type ExternalMcpArgumentIssue,
} from "./external-mcp-tool-arguments.js"
import { compareCapabilityMatches, tokenize } from "./search.js"
import type { CapabilityMatch } from "./search.js"
import {
codemodeScriptPath,
resolveCodemodeConnectionNamespaceContext,
type CodemodeConnectionNamespaceContext,
} from "./codemode-namespaces.js"
import {
getExternalToolsSearchCache,
setExternalToolsSearchCache,
type ExternalToolsSearchCacheKey,
} from "./external-tools-search-cache.js"
/**
* Merges org-level External MCP Connections (capability-sources/) into the
* same search_capabilities/execute_capability surface as the REST-derived
* catalog (catalog.ts), without touching that catalog or the rich `/mcp`
* endpoint at all. A connected external tool is namespaced
* `mcp:<connectionId>:<toolName>` so execute_capability can tell it apart
* from a REST operation name and dispatch to the real MCP client
* (external-mcp-client.ts) instead of invokeMcpOperation.
*
* Everything here is scoped to the CALLING MEMBER, not just the org:
* - Only connections the member has been granted (org-wide, direct, or via
* a team) are searchable/executable. Access is never implicit.
* - For credentialMode "per_member" connections, calls run with the
* member's own connected account; if they haven't connected one yet,
* search surfaces the connection as needs_connection (so the agent can
* tell the human what to do) instead of silently hiding it.
*/
const EXTERNAL_CAPABILITY_PREFIX = "mcp:"
export const EXTERNAL_MCP_SEARCH_CONNECTION_LIMIT = 16
export const EXTERNAL_MCP_SEARCH_CONCURRENCY = 8
export const EXTERNAL_MCP_SEARCH_MATCH_LIMIT = 20
const EXTERNAL_MCP_SEARCH_REQUEST_TIMEOUT_MS = 5_000
const EXTERNAL_MCP_SEARCH_LIFECYCLE_TIMEOUT_MS = 8_000
export function buildExternalCapabilityName(connectionId: string, toolName: string): string {
return `${EXTERNAL_CAPABILITY_PREFIX}${connectionId}:${toolName}`
}
export function parseExternalCapabilityName(name: string): { connectionId: string; toolName: string } | null {
if (!name.startsWith(EXTERNAL_CAPABILITY_PREFIX)) return null
const rest = name.slice(EXTERNAL_CAPABILITY_PREFIX.length)
const separatorIndex = rest.indexOf(":")
if (separatorIndex <= 0) return null
return {
connectionId: rest.slice(0, separatorIndex),
toolName: rest.slice(separatorIndex + 1),
}
}
export type McpMemberIdentity = {
orgMembershipId: DenTypeId<"member">
teamIds: DenTypeId<"team">[]
}
/**
* Resolves the MCP principal (userId + organizationId from the bearer
* token) to the member identity the grant checks need. Returns null when
* the user has no active membership — callers should treat that as
* zero external-capability access, not an error.
*/
export async function resolveMcpMemberIdentity(input: {
userId: string
organizationId: string
}): Promise<McpMemberIdentity | null> {
const organizationId = normalizeDenTypeId("organization", input.organizationId)
const member = await cache.org.membership({
organizationId,
userId: normalizeDenTypeId("user", input.userId),
})
if (!member) return null
const teams = await listTeamsForMember({ organizationId, memberId: member.id })
return { orgMembershipId: member.id, teamIds: teams.map((team) => team.id) }
}
function hasSharedCredential(connection: ExternalMcpConnectionRow): boolean {
if (connection.oauthIssuerReviewRequiredAt) return false
if (connection.authType === "oauth") return Boolean(connection.accessToken)
if (connection.authType === "apikey") return Boolean(connection.apiKey)
return true
}
function redirectUriFor(redirectUriBase: string, connectionId: string): string {
return `${redirectUriBase}/v1/mcp-connections/${encodeURIComponent(connectionId)}/connect/callback`
}
function scoreText(nameTokens: string[], summaryTokens: string[], queryTokens: string[]): number {
let score = 0
for (const queryToken of queryTokens) {
if (nameTokens.includes(queryToken)) {
score += 5
} else if (nameTokens.some((token) => token.startsWith(queryToken) || queryToken.startsWith(token))) {
score += 3
}
if (summaryTokens.includes(queryToken)) {
score += 2
}
}
return score
}
/**
* A capability search must never turn an unbounded org connection list into
* unbounded remote handshakes. Prefer connections whose names match the
* query, keep source order as the deterministic tiebreaker, and enforce one
* hard fanout ceiling before any provider network request is started.
*/
export function selectExternalMcpSearchConnections<T extends { name: string }>(
connections: readonly T[],
queryTokens: string[],
limit = EXTERNAL_MCP_SEARCH_CONNECTION_LIMIT,
): T[] {
return connections
.map((connection, index) => ({
connection,
index,
score: scoreText(tokenize(connection.name), tokenize(connection.name), queryTokens),
}))
.sort((left, right) => right.score - left.score || left.index - right.index)
.slice(0, Math.max(0, Math.min(limit, EXTERNAL_MCP_SEARCH_CONNECTION_LIMIT)))
.map(({ connection }) => connection)
}
export type ExternalCapabilityMatch = CapabilityMatch & {
/** Exact MCP arguments schema returned by the provider's live tools/list. */
argumentsSchema?: unknown
/** Stable digest used to detect a schema change between search and execute. */
schemaDigest?: string
/** Tells the generic execute facade where MCP arguments must be supplied. */
invocation?: { argumentsField: "body" }
/** Distinguishes a connection-health result from a callable capability. */
kind?: "connection_status" | "mcp_app"
/** Set for connection-level status rows: the tool exists but needs a human/admin fix before real tools can be listed. */
status?: "needs_connection" | "error"
hint?: string
connectionStatus?: ExternalConnectionStatus
}
export type ExternalMcpAppLaunch = {
connectionId: string
toolName: string
resourceUri: string
arguments: Record<string, unknown>
}
export type ExternalConnectionStatus = {
version: typeof OMNIRUSH_CLOUD_MCP_CONNECTION_ACTION_VERSION
kind: typeof OMNIRUSH_CLOUD_MCP_CONNECTION_ACTION_KIND
source: typeof OMNIRUSH_CLOUD_MCP_CONNECTION_ACTION_SOURCE
layer: "mcp_connection" | "downstream_provider"
connectionId: string
connectionName: string
authType: "oauth" | "apikey" | "none"
credentialMode: "shared" | "per_member"
state: "needs_connection" | "reauth_required" | "provider_error"
errorCode: "not_connected" | "invalid_refresh_token" | "invalid_grant" | "unauthorized" | "provider_error"
message: string
actor: ExternalMcpDiagnostic["actionOwner"]
action: {
type: "connect" | "reconnect" | "update_credentials" | "inspect_connection" | "fix_provider" | "fix_network" | "contact_omnirush"
label: string
surface: "omnirush_your_connections" | "omnirush_organization_connections" | "provider_admin_console" | "network_infrastructure" | "omnirush_support"
retry: "search_capabilities"
url?: string
}
}
type ConnectionStatusIdentity = {
id: string
name: string
authType: ExternalConnectionStatus["authType"]
credentialMode: ExternalConnectionStatus["credentialMode"]
}
const ERROR_MESSAGE_LIMIT = 300
const LIVE_PROBE_HINT = "This is a live probe, not a cached result — repeating the same search without changing anything will return the same error."
const INVALID_REFRESH_TOKEN_PATTERN = /\binvalid[ _-]?refresh[ _-]?token\b/i
const INVALID_GRANT_PATTERN = /\binvalid[ _-]?grant\b/i
const UNAUTHORIZED_PATTERN = /\b(?:unauthori[sz]ed|invalid[ _-]?token|token (?:is )?expired|expired (?:access )?token)\b/i
const PROVIDER_ADMIN_ACTION_PATTERN = /\b(?:app (?:is )?not installed|admin(?:istrator)? (?:consent|approval)|approval required)\b/i
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value)
}
export function externalMcpAppResourceUri(tool: { _meta?: unknown }): string | null {
const meta = isRecord(tool._meta) ? tool._meta : {}
const ui = isRecord(meta.ui) ? meta.ui : {}
const resourceUri = typeof ui.resourceUri === "string"
? ui.resourceUri
: typeof meta["ui/resourceUri"] === "string"
? meta["ui/resourceUri"]
: null
return resourceUri?.startsWith("ui://") ? resourceUri : null
}
function cappedErrorMessage(message: string): string {
return message.length > ERROR_MESSAGE_LIMIT ? `${message.slice(0, ERROR_MESSAGE_LIMIT)}...` : message
}
function parsedErrorMessage(value: unknown): string | null {
if (!isRecord(value)) return null
const nestedError = value.error
if (isRecord(nestedError) && typeof nestedError.message === "string") {
return typeof nestedError.code === "number"
? `${nestedError.message} (JSON-RPC ${nestedError.code})`
: nestedError.message
}
if (typeof value.message === "string") return value.message
if (typeof nestedError === "string") return nestedError
return null
}
function errorCauseChain(error: unknown): unknown[] {
const chain: unknown[] = []
let current: unknown = error
for (let depth = 0; depth < 6; depth += 1) {
chain.push(current)
if (!isRecord(current) || !("cause" in current) || current.cause === undefined) break
current = current.cause
}
return chain
}
export function upstreamErrorMessage(error: unknown): string {
const chain = errorCauseChain(error)
const diagnosticError = chain.find((current) => current instanceof ExternalMcpDiagnosticError)
if (diagnosticError instanceof ExternalMcpDiagnosticError) return diagnosticError.diagnostic.message
for (const current of [...chain].reverse()) {
const message = current instanceof Error ? current.message : String(current)
const jsonStart = message.indexOf("{")
if (jsonStart >= 0) {
try {
const parsed: unknown = JSON.parse(message.slice(jsonStart))
const parsedMessage = parsedErrorMessage(parsed)
if (parsedMessage) return parsedMessage
} catch {
// Try the next cause when the SDK wrapper contains partial or invalid JSON.
}
}
if (message.trim()) return cappedErrorMessage(message)
}
return "Unknown MCP provider error."
}
export function externalMcpAuthErrorCode(
error: unknown,
message = upstreamErrorMessage(error),
): ExternalConnectionStatus["errorCode"] | null {
const diagnosticError = errorCauseChain(error)
.find((current) => current instanceof ExternalMcpDiagnosticError)
if (diagnosticError instanceof ExternalMcpDiagnosticError) {
if (diagnosticError.diagnostic.code === "MCP_OAUTH_INVALID_GRANT") return "invalid_grant"
if (
diagnosticError.diagnostic.phase === "AUTH_TOKEN_ACQUISITION"
|| diagnosticError.diagnostic.phase === "AUTH_RESOURCE_VALIDATION"
|| diagnosticError.diagnostic.phase === "CONTINUITY_REFRESH"
) return "unauthorized"
}
if (INVALID_REFRESH_TOKEN_PATTERN.test(message)) return "invalid_refresh_token"
if (INVALID_GRANT_PATTERN.test(message)) return "invalid_grant"
if (
errorCauseChain(error).some((current) => (
current instanceof UnauthorizedError
|| (current instanceof StreamableHTTPError && (current.code === 401 || current.code === 403))
))
|| UNAUTHORIZED_PATTERN.test(message)
) return "unauthorized"
return null
}
export function isExternalMcpAuthError(error: unknown): boolean {
return externalMcpAuthErrorCode(error) !== null
}
export function externalConnectionErrorHint(
connectionName: string,
error: unknown,
message = upstreamErrorMessage(error),
credentialMode: ExternalMcpConnectionRow["credentialMode"] = "shared",
): string {
if (error instanceof ExternalMcpDiagnosticError) {
return `${error.diagnostic.message} Ask the named action owner to inspect this layer. ${error.diagnostic.operatorAction} Diagnostic reference: ${error.diagnostic.referenceId}. ${LIVE_PROBE_HINT}`
}
if (externalMcpAuthErrorCode(error, message)) {
const destination = credentialMode === "per_member"
? "OmniRush.ai Cloud -> Your Connections"
: "the OmniRush.ai Cloud dashboard -> Connections"
return `The stored credential for "${connectionName}" is invalid or expired. Reconnect "${connectionName}" from ${destination}, then search again. OmniRush.ai Cloud itself is still connected. ${LIVE_PROBE_HINT}`
}
if (PROVIDER_ADMIN_ACTION_PATTERN.test(message)) {
return `The provider's server rejected the request for "${connectionName}": ${message}. A provider admin must fix it in the provider's own admin console, then search again. OmniRush.ai Cloud itself is still connected. ${LIVE_PROBE_HINT}`
}
return `The downstream provider for "${connectionName}" returned an error: ${message}. Ask an org admin to inspect "${connectionName}" in the OmniRush.ai Cloud dashboard -> Connections, then search again. OmniRush.ai Cloud itself is still connected. ${LIVE_PROBE_HINT}`
}
function diagnosticConnectionAction(input: {
connection: Pick<ExternalMcpConnectionRow, "authType">
state: ExternalConnectionStatus["state"]
diagnostic: ExternalMcpDiagnostic
}): Pick<ExternalConnectionStatus, "actor" | "action"> {
const actor = input.diagnostic.actionOwner
let type: ExternalConnectionStatus["action"]["type"]
let surface: ExternalConnectionStatus["action"]["surface"]
if (actor === "omnirush") {
type = "contact_omnirush"
surface = "omnirush_support"
} else if (actor === "network_admin") {
type = "fix_network"
surface = "network_infrastructure"
} else if (actor === "provider_admin") {
type = "fix_provider"
surface = "provider_admin_console"
} else if (actor === "member") {
type = input.state === "needs_connection" ? "connect" : "reconnect"
surface = "omnirush_your_connections"
} else {
type = input.state === "reauth_required"
? input.connection.authType === "apikey" ? "update_credentials" : "reconnect"
: "inspect_connection"
surface = "omnirush_organization_connections"
}
return {
actor,
action: {
type,
surface,
label: input.diagnostic.operatorAction,
retry: "search_capabilities",
},
}
}
function actionNavigationUrl(input: {
connectionId: string
surface: ExternalConnectionStatus["action"]["surface"]
}) {
if (input.surface === "omnirush_your_connections") return omnirushYourConnectionsUrl(input.connectionId)
if (input.surface === "omnirush_organization_connections") return omnirushOrganizationConnectionsUrl()
return undefined
}
function addConnectionActionUrl(input: {
action: ExternalConnectionStatus["action"]
connectionId: string
}): ExternalConnectionStatus["action"] {
const url = actionNavigationUrl({ connectionId: input.connectionId, surface: input.action.surface })
return url ? { ...input.action, url } : input.action
}
function relayableProviderConnectUrl(connectUrl: string | undefined, connectionUrl: string): string | undefined {
if (!connectUrl) return undefined
try {
const candidate = new URL(connectUrl)
const connection = new URL(connectionUrl)
if (candidate.host !== connection.host) return undefined
return candidate.protocol === "http:" || candidate.protocol === "https:" ? candidate.toString() : undefined
} catch {
return undefined
}
}
function providerAuthorizationDiagnosticForConnection(input: {
diagnostic: ExternalMcpDiagnostic
connectionUrl: string
}): ExternalMcpDiagnostic {
if (!input.diagnostic.connectUrl) return input.diagnostic
const connectUrl = relayableProviderConnectUrl(input.diagnostic.connectUrl, input.connectionUrl)
if (!connectUrl) {
const diagnostic = { ...input.diagnostic }
delete diagnostic.connectUrl
return diagnostic
}
return connectUrl === input.diagnostic.connectUrl
? input.diagnostic
: { ...input.diagnostic, connectUrl }
}
function providerAuthorizationConnectionStatus(input: {
connection: Pick<ExternalMcpConnectionRow, "id" | "name" | "authType" | "credentialMode">
diagnostic: ExternalMcpDiagnostic
message: string
}): ExternalConnectionStatus {
const status = buildExternalConnectionStatus({
connection: input.connection,
state: "needs_connection",
errorCode: "not_connected",
message: input.message,
diagnostic: input.diagnostic,
actionOwner: "member",
layer: "downstream_provider",
})
return {
...status,
actor: "member",
action: {
type: "connect",
label: "Connect your provider account",
surface: "omnirush_your_connections",
retry: "search_capabilities",
...(input.diagnostic.connectUrl ? { url: input.diagnostic.connectUrl } : {}),
},
}
}
export function buildExternalConnectionStatus(input: {
connection: ConnectionStatusIdentity
state: ExternalConnectionStatus["state"]
errorCode: ExternalConnectionStatus["errorCode"]
message: string
diagnostic?: ExternalMcpDiagnostic
actionOwner?: "member" | "organization_admin"
layer?: ExternalConnectionStatus["layer"]
}): ExternalConnectionStatus {
const connectionName = input.connection.name
const actionContract = {
version: OMNIRUSH_CLOUD_MCP_CONNECTION_ACTION_VERSION,
kind: OMNIRUSH_CLOUD_MCP_CONNECTION_ACTION_KIND,
source: OMNIRUSH_CLOUD_MCP_CONNECTION_ACTION_SOURCE,
} as const
// Once the failure is classified as reauthentication, credential ownership
// is the source of truth for who can repair it. A generic HTTP 400 during a
// refresh may classify the raw diagnostic as provider_admin, but routing a
// per-member expired token to a provider console contradicts the
// reauth_required state and prevents the client from offering reconnect.
const diagnosticAction = input.diagnostic && input.state !== "reauth_required"
? diagnosticConnectionAction({ connection: input.connection, state: input.state, diagnostic: input.diagnostic })
: null
if (input.state === "provider_error") {
const providerAdminAction = PROVIDER_ADMIN_ACTION_PATTERN.test(input.message)
return {
...actionContract,
layer: input.layer ?? (input.diagnostic ? "mcp_connection" : "downstream_provider"),
connectionId: input.connection.id,
connectionName,
authType: input.connection.authType,
credentialMode: input.connection.credentialMode,
state: input.state,
errorCode: input.errorCode,
message: input.message,
actor: diagnosticAction?.actor ?? (providerAdminAction ? "provider_admin" : "organization_admin"),
action: diagnosticAction
? addConnectionActionUrl({ action: diagnosticAction.action, connectionId: input.connection.id })
: addConnectionActionUrl({
connectionId: input.connection.id,
action: {
type: providerAdminAction ? "fix_provider" : "inspect_connection",
label: providerAdminAction
? `Fix ${connectionName} in the provider admin console`
: `Inspect the ${connectionName} connection`,
surface: providerAdminAction ? "provider_admin_console" : "omnirush_organization_connections",
retry: "search_capabilities",
},
}),
}
}
const actor = input.actionOwner
?? (input.connection.credentialMode === "per_member" ? "member" : "organization_admin")
const surface = actor === "member"
? "omnirush_your_connections"
: "omnirush_organization_connections"
const actionType = input.state === "needs_connection"
? "connect"
: input.connection.authType === "oauth"
? "reconnect"
: input.connection.authType === "apikey"
? "update_credentials"
: "inspect_connection"
const actionVerb = actionType === "connect"
? "Connect"
: actionType === "reconnect"
? "Reconnect"
: actionType === "update_credentials"
? "Update credentials for"
: "Inspect"
return {
...actionContract,
layer: input.layer ?? (input.diagnostic ? "mcp_connection" : "downstream_provider"),
connectionId: input.connection.id,
connectionName,
authType: input.connection.authType,
credentialMode: input.connection.credentialMode,
state: input.state,
errorCode: input.errorCode,
message: input.message,
actor: diagnosticAction?.actor ?? actor,
action: diagnosticAction
? addConnectionActionUrl({ action: diagnosticAction.action, connectionId: input.connection.id })
: addConnectionActionUrl({
connectionId: input.connection.id,
action: {
type: actionType,
label: `${actionVerb} ${connectionName}`,
surface,
retry: "search_capabilities",
},
}),
}
}
function statusMatch(input: {
connection: ExternalMcpConnectionRow
score: number
summary: string
status: ExternalCapabilityMatch["status"]
hint: string
connectionStatus: ExternalConnectionStatus
}): ExternalCapabilityMatch {
return {
name: buildExternalCapabilityName(input.connection.id, "*"),
method: "MCP",
path: input.connection.url,
score: input.score,
summary: input.summary,
pathParams: [],
queryParams: [],
hasBody: false,
kind: "connection_status",
status: input.status,
hint: input.hint,
connectionStatus: input.connectionStatus,
}
}
export function mergeBoundedExternalCapabilityMatches(
retained: ExternalCapabilityMatch[],
candidates: readonly ExternalCapabilityMatch[],
limit: number,
): ExternalCapabilityMatch[] {
const boundedLimit = Number.isFinite(limit)
? Math.max(0, Math.min(Math.floor(limit), EXTERNAL_MCP_SEARCH_MATCH_LIMIT))
: 0
if (boundedLimit === 0) {
retained.splice(0)
return retained
}
for (const candidate of candidates) {
retained.push(candidate)
retained.sort(compareCapabilityMatches)
if (retained.length > boundedLimit) retained.splice(boundedLimit)
}
return retained
}
export async function collectBoundedExternalMcpSearchMatches<T>(input: {
connections: readonly T[]
deadline: ExternalMcpLifecycleDeadline
limit: number
concurrency?: number
probe: (connection: T, deadline: ExternalMcpLifecycleDeadline) => Promise<ExternalCapabilityMatch[]>
}): Promise<ExternalCapabilityMatch[]> {
const retained: ExternalCapabilityMatch[] = []
const boundedLimit = Number.isFinite(input.limit)
? Math.max(0, Math.min(Math.floor(input.limit), EXTERNAL_MCP_SEARCH_MATCH_LIMIT))
: 0
if (boundedLimit === 0 || input.connections.length === 0) return retained
const concurrency = Math.max(1, Math.min(
Math.floor(input.concurrency ?? EXTERNAL_MCP_SEARCH_CONCURRENCY),
EXTERNAL_MCP_SEARCH_CONCURRENCY,
input.connections.length,
))
let nextIndex = 0
let acceptingResults = true
const worker = async () => {
while (Date.now() < input.deadline.expiresAt) {
const index = nextIndex
nextIndex += 1
if (index >= input.connections.length) return
const candidates = await input.probe(input.connections[index]!, input.deadline)
if (acceptingResults) mergeBoundedExternalCapabilityMatches(retained, candidates, boundedLimit)
}
}
const workers = Promise.all(Array.from({ length: concurrency }, () => worker()))
const remaining = Math.max(0, input.deadline.expiresAt - Date.now())
let deadlineTimer: ReturnType<typeof setTimeout> | undefined
const deadlineReached = new Promise<void>((resolve) => {
deadlineTimer = setTimeout(resolve, remaining)
})
try {
await Promise.race([workers, deadlineReached])
} finally {
acceptingResults = false
if (deadlineTimer) clearTimeout(deadlineTimer)
// Active MCP requests receive the same absolute deadline and abort their
// fetch at this point. Keep a rejection observer on the worker pool for
// the smaller class of non-fetch operations that cannot be cancelled.
void workers.catch(() => undefined)
}
return retained
}
export type ExternalMcpSearchCoverage = {
eligibleConnections: number
probedConnections: number
truncated: boolean
}
export function externalMcpSearchCoverageHint(coverage: ExternalMcpSearchCoverage): string | undefined {
if (!coverage.truncated) return undefined
return `External MCP search inspected ${coverage.probedConnections} of ${coverage.eligibleConnections} eligible connections. Results may be incomplete; narrow the query using a connection name and search again.`
}
const CONNECTION_CARD_HINT = "Execute this exact capability name once: it returns the live status, renders an actionable connection card for the member in compatible hosts, and includes the action to relay in text."
async function probeExternalMcpConnection(input: {
connection: ExternalMcpConnectionRow
member: McpMemberIdentity
queryTokens: string[]
redirectUriBase: string
limit: number
deadline: ExternalMcpLifecycleDeadline
scriptNamespace?: string
}): Promise<ExternalCapabilityMatch[]> {
const matches: ExternalCapabilityMatch[] = []
const add = (match: ExternalCapabilityMatch) => {
mergeBoundedExternalCapabilityMatches(matches, [match], input.limit)
}
const connection = input.connection
if (connection.toolPolicy?.allDisabled) return matches
if (connection.oauthIssuerReviewRequiredAt) {
const nameTokens = tokenize(connection.name)
const score = scoreText(nameTokens, nameTokens, input.queryTokens)
if (score > 0) {
const message = `${connection.name} is blocked until an organization admin reviews its changed OAuth issuer.`
add(statusMatch({
connection,
score,
summary: `[${connection.name}] OAuth provider settings changed and require administrator review.`,
status: "error",
hint: `Ask an org admin to open OmniRush.ai Cloud -> Connectors, review the live OAuth issuer for "${connection.name}", and reconnect if requested. ${CONNECTION_CARD_HINT}`,
connectionStatus: buildExternalConnectionStatus({
connection,
state: "reauth_required",
errorCode: "unauthorized",
message,
actionOwner: "organization_admin",
}),
}))
}
return matches
}
if (connection.credentialMode === "per_member") {
const account = await getConnectedAccount({
organizationId: connection.organizationId,
orgMembershipId: input.member.orgMembershipId,
providerId: connection.id,
})
if (!account?.accessToken) {
// Granted but not yet connected: surface the connection itself (not
// its tools — we can't list them without the member's credential) so
// the agent can tell the human exactly what to do.
const nameTokens = tokenize(connection.name)
const score = scoreText(nameTokens, nameTokens, input.queryTokens)
if (score > 0) {
const message = `You haven't connected your ${connection.name} account yet.`
add(statusMatch({
connection,
score,
summary: `[${connection.name}] Available to you, but you haven't connected your ${connection.name} account yet.`,
status: "needs_connection",
hint: `Ask the user to click Connect on the "${connection.name}" card in OmniRush.ai desktop, then search again. In clients without inline connection controls, use OmniRush.ai Cloud -> Your Connections. ${CONNECTION_CARD_HINT}`,
connectionStatus: buildExternalConnectionStatus({ connection, state: "needs_connection", errorCode: "not_connected", message }),
}))
}
return matches
}
} else if (!hasSharedCredential(connection)) {
const nameTokens = tokenize(connection.name)
const score = scoreText(nameTokens, nameTokens, input.queryTokens)
if (score > 0) {
const message = `${connection.name} is not connected yet.`
add(statusMatch({
connection,
score,
summary: `[${connection.name}] Available to your organization, but an admin hasn't connected it yet.`,
status: "needs_connection",
hint: `Ask an org admin to open the OmniRush.ai Cloud dashboard -> Connections and connect "${connection.name}", then search again. ${CONNECTION_CARD_HINT}`,
connectionStatus: buildExternalConnectionStatus({ connection, state: "needs_connection", errorCode: "not_connected", message }),
}))
}
return matches
}
const member = connection.credentialMode === "per_member"
? { orgMembershipId: input.member.orgMembershipId }
: undefined
let tools: Awaited<ReturnType<typeof listExternalMcpTools>>
const cacheKey: ExternalToolsSearchCacheKey = {
organizationId: connection.organizationId,
connectionId: connection.id,
updatedAt: connection.updatedAt,
credentialMode: connection.credentialMode,
...(connection.credentialMode === "per_member" ? { orgMembershipId: input.member.orgMembershipId } : {}),
}
const cachedProbe = getExternalToolsSearchCache(cacheKey)
try {
if (cachedProbe?.outcome === "failure") throw cachedProbe.error
if (cachedProbe?.outcome === "success") {
tools = cachedProbe.tools
} else {
tools = await listExternalMcpTools(
connection,
redirectUriFor(input.redirectUriBase, connection.id),
member,
undefined,
input.deadline,
EXTERNAL_MCP_SEARCH_REQUEST_TIMEOUT_MS,
)
setExternalToolsSearchCache(cacheKey, { outcome: "success", tools })
}
} catch (error) {
if (!cachedProbe) setExternalToolsSearchCache(cacheKey, { outcome: "failure", error })
const message = upstreamErrorMessage(error)
const diagnostic = error instanceof ExternalMcpDiagnosticError ? error.diagnostic : undefined
const nameTokens = tokenize(connection.name)
const score = scoreText(nameTokens, nameTokens, input.queryTokens)
if (score > 0) {
if (diagnostic) {
console.error("external_mcp_capability_search_probe_failed", {
connectionId: connection.id,
organizationId: connection.organizationId,
connectionEndpoint: safeExternalMcpEndpointForLog(connection.url),
...externalMcpDiagnosticForLog(error, diagnostic.referenceId, "MCP_TOOL_DISCOVERY"),
})
}
const authErrorCode = externalMcpAuthErrorCode(error, message)
const state = authErrorCode ? "reauth_required" : "provider_error"
add(statusMatch({
connection,
score,
summary: `[${connection.name}] This connection is set up but returned an error (${message}).`,
status: "error",
hint: `${externalConnectionErrorHint(connection.name, error, message, connection.credentialMode)} ${CONNECTION_CARD_HINT}`,
connectionStatus: buildExternalConnectionStatus({
connection,
state,
errorCode: authErrorCode ?? "provider_error",
message,
diagnostic,
}),
}))
}
return matches
}
for (const tool of tools) {
if (isToolDisabled(connection.toolPolicy, tool.name)) continue
const summary = tool.description ?? tool.title ?? tool.name
const nameTokens = tokenize(`${connection.name} ${tool.name}`)
const summaryTokens = tokenize(summary)
const score = scoreText(nameTokens, summaryTokens, input.queryTokens)
if (score <= 0) continue
const resourceUri = externalMcpAppResourceUri(tool)
add({
name: buildExternalCapabilityName(connection.id, tool.name),
method: "MCP",
path: connection.url,
score,
summary: `[${connection.name}] ${summary}`,
pathParams: [],
queryParams: [],
hasBody: true,
argumentsSchema: tool.inputSchema,
schemaDigest: externalMcpToolSchemaDigest(tool.inputSchema),
invocation: { argumentsField: "body" },
...(resourceUri ? { kind: "mcp_app" as const, mcpApp: { resourceUri } } : {}),
...(input.scriptNamespace ? { scriptPath: codemodeScriptPath(input.scriptNamespace, tool.name) } : {}),
})
}
return matches
}
/**
* Live-lists tools for a bounded set of external MCP connections the calling
* member has been granted. All probes share one absolute deadline and run in
* a small worker pool; one unreachable server cannot serialize the latency of
* every other provider or let matches grow beyond the requested top-K.
*/
export async function searchExternalCapabilities(input: {
organizationId: string
member: McpMemberIdentity | null
query: string
redirectUriBase: string
limit?: number
namespaceContext?: CodemodeConnectionNamespaceContext
reportCoverage?: (coverage: ExternalMcpSearchCoverage) => void
}): Promise<ExternalCapabilityMatch[]> {
if (!input.member) return []
const queryTokens = tokenize(input.query)
if (queryTokens.length === 0) return []
const requestedLimit = input.limit ?? 5
if (!Number.isFinite(requestedLimit) || requestedLimit <= 0) return []
const limit = Math.min(Math.max(1, Math.trunc(requestedLimit)), EXTERNAL_MCP_SEARCH_MATCH_LIMIT)
const deadline = createExternalMcpLifecycleDeadline(EXTERNAL_MCP_SEARCH_LIFECYCLE_TIMEOUT_MS)
const namespaceContext = input.namespaceContext ?? await resolveCodemodeConnectionNamespaceContext({
organizationId: input.organizationId,
member: input.member,
})
const connections = namespaceContext?.externalMcpConnections ?? await listUsableExternalMcpConnections({
organizationId: normalizeDenTypeId("organization", input.organizationId),
orgMembershipId: input.member.orgMembershipId,
teamIds: input.member.teamIds,
})
const scriptNamespaces = namespaceContext?.namespaces.externalMcp
const selectedConnections = selectExternalMcpSearchConnections(connections, queryTokens)
input.reportCoverage?.({
eligibleConnections: connections.length,
probedConnections: selectedConnections.length,
truncated: selectedConnections.length < connections.length,
})
return await collectBoundedExternalMcpSearchMatches({
connections: selectedConnections,
deadline,
limit,
probe: (connection, sharedDeadline) => probeExternalMcpConnection({
connection,
member: input.member!,
queryTokens,
redirectUriBase: input.redirectUriBase,
limit,
deadline: sharedDeadline,
scriptNamespace: scriptNamespaces?.get(connection.id),
}),
})
}
export type ExternalMcpSchemaWarning =
| {
code: "arguments_schema_mismatch"
message: string
issues: ExternalMcpArgumentIssue[]
suggestedAction: string
}
| {
code: "arguments_schema_unavailable"
message: string
suggestedAction: string
}
| {
code: "capability_schema_changed"
message: string
searchedSchemaDigest: string
currentSchemaDigest: string
suggestedAction: string
}
export type ExternalMcpSchemaGuidance = {
advisory: true
providerCallAttempted: true
message: string
warnings: ExternalMcpSchemaWarning[]
}
export type ExternalCapabilityExecuteResult =
| {
ok: true
result: Awaited<ReturnType<typeof callExternalMcpTool>>
schemaGuidance?: ExternalMcpSchemaGuidance
mcpApp?: ExternalMcpAppLaunch
}
| {
ok: false
error:
| "unknown_capability"
| "forbidden"
| "connection_not_connected"
| "needs_connection"
| "connection_failed"
| "provider_error"
| "invalid_capability_arguments"
| "policy_blocked"
message: string
referenceId?: string
retryable?: boolean
providerError?: ExternalMcpProviderError
connectionStatus?: ExternalConnectionStatus
capability?: string
issues?: ExternalMcpArgumentIssue[]
schemaDigest?: string
sameArgumentsRetryable?: false
retry?: {
action: "correct_arguments" | "search_capabilities"
searchRequired: boolean
}
schemaGuidance?: ExternalMcpSchemaGuidance
}
export type ExternalMcpProviderError = {
jsonRpcCode?: number
message?: string
data?: string
}
function providerErrorFromDiagnostic(diagnostic: ExternalMcpDiagnostic): ExternalMcpProviderError | undefined {
if (
diagnostic.jsonRpcCode === undefined
&& !diagnostic.providerErrorMessage
&& !diagnostic.providerErrorData
) return undefined
return {
...(diagnostic.jsonRpcCode === undefined ? {} : { jsonRpcCode: diagnostic.jsonRpcCode }),
...(diagnostic.providerErrorMessage ? { message: diagnostic.providerErrorMessage } : {}),
...(diagnostic.providerErrorData ? { data: diagnostic.providerErrorData } : {}),
}
}
function diagnosticAgentMessage(diagnostic: ExternalMcpDiagnostic): string {
return `${diagnostic.message} ${diagnostic.operatorAction} Diagnostic reference: ${diagnostic.referenceId}.`
}
function diagnosticAgentFields(diagnostic: ExternalMcpDiagnostic) {
const providerError = providerErrorFromDiagnostic(diagnostic)
return {
referenceId: diagnostic.referenceId,
retryable: diagnostic.retryable,
...(providerError ? { providerError } : {}),
}
}
function invalidCapabilityArguments(input: {
capability: string
schemaDigest?: string
issues?: ExternalMcpArgumentIssue[]
diagnostic?: ExternalMcpDiagnostic
schemaGuidance?: ExternalMcpSchemaGuidance
}): Exclude<ExternalCapabilityExecuteResult, { ok: true }> {
return {
ok: false,
error: "invalid_capability_arguments",
capability: input.capability,
message: input.diagnostic
? diagnosticAgentMessage(input.diagnostic)
: "The capability arguments do not match the remote MCP tool's advertised argumentsSchema.",
issues: input.issues ?? [{
path: "/",
keyword: "schema_validation",
message: "The remote MCP rejected these arguments as invalid. Correct them using the latest argumentsSchema.",
}],
...(input.schemaDigest ? { schemaDigest: input.schemaDigest } : {}),
sameArgumentsRetryable: false,
retry: { action: "correct_arguments", searchRequired: false },
...(input.schemaGuidance ? { schemaGuidance: input.schemaGuidance } : {}),
...(input.diagnostic ? diagnosticAgentFields(input.diagnostic) : {}),
}
}
function advisorySchemaGuidance(
warnings: ExternalMcpSchemaWarning[],
): ExternalMcpSchemaGuidance | undefined {
if (warnings.length === 0) return undefined
return {
advisory: true,
providerCallAttempted: true,
message: "OmniRush.ai forwarded the call to the provider. These local schema checks are guidance only; use the provider result as the source of truth.",
warnings,
}
}
export type ExternalConnectionProbe =
| { ok: true; connected: true; connection: { id: string; name: string } }
| { ok: true; connected: false; status: ExternalConnectionStatus }
| { ok: false; error: "forbidden" | "unknown_capability"; message: string }
/**
* Probes one connection's live credential state without calling provider
* tools. Backs the connection_status capability execution and the app-only
* connection_action tool, so the same check renders the connection card and
* refreshes it after the member fixes the connection.
*/
export async function probeExternalConnectionStatus(input: {
organizationId: string
member: McpMemberIdentity | null
connectionId: string
}): Promise<ExternalConnectionProbe> {
if (!input.member) {
return { ok: false, error: "forbidden", message: "No active org membership for this token." }
}
let connection: Awaited<ReturnType<typeof getExternalMcpConnection>>
let connectionId: DenTypeId<"externalMcpConnection">
try {
connectionId = normalizeDenTypeId("externalMcpConnection", input.connectionId)
connection = await getExternalMcpConnection({
organizationId: normalizeDenTypeId("organization", input.organizationId),
connectionId,
})
} catch {
connection = null
connectionId = input.connectionId as DenTypeId<"externalMcpConnection">
}
if (!connection || connection.kind !== "external_mcp") {
return { ok: false, error: "unknown_capability", message: `No external MCP connection "${input.connectionId}" in this organization.` }
}
const canUse = await memberCanUseExternalMcpConnection({
connectionId,
orgMembershipId: input.member.orgMembershipId,
teamIds: input.member.teamIds,
})
if (!canUse) {
return { ok: false, error: "forbidden", message: `You have not been granted access to "${connection.name}".` }
}
if (connection.oauthIssuerReviewRequiredAt) {
const message = `"${connection.name}" is blocked until an organization admin reviews its changed OAuth issuer.`
return {
ok: true,
connected: false,
status: buildExternalConnectionStatus({
connection,
state: "reauth_required",
errorCode: "unauthorized",
message,
actionOwner: "organization_admin",
}),
}
}
if (connection.credentialMode === "per_member") {
const account = await getConnectedAccount({
organizationId: connection.organizationId,
orgMembershipId: input.member.orgMembershipId,
providerId: connection.id,
})
if (!account?.accessToken) {
const message = `You haven't connected your ${connection.name} account yet.`
return {
ok: true,
connected: false,
status: buildExternalConnectionStatus({ connection, state: "needs_connection", errorCode: "not_connected", message }),
}
}
} else if (!hasSharedCredential(connection)) {
const message = `"${connection.name}" is not connected yet.`
return {
ok: true,
connected: false,
status: buildExternalConnectionStatus({ connection, state: "needs_connection", errorCode: "not_connected", message }),
}
}
return { ok: true, connected: true, connection: { id: connection.id, name: connection.name } }
}
/**
* Executes a namespaced external capability, scoped to the calling
* principal's org AND member: the member must hold a grant (org-wide,
* direct, or team), and for per-member connections must have connected
* their own account — the call then runs as them.
*/
export async function executeExternalCapability(input: {
organizationId: string
member: McpMemberIdentity | null
connectionId: string
toolName: string
args: unknown
schemaDigest?: string
redirectUriBase: string
/** Fail closed unless the live provider catalog still marks this exact tool read-only. */
requireReadOnly?: boolean
/** Fail closed when the live input schema no longer matches schemaDigest. */
requireSchemaMatch?: boolean
}): Promise<ExternalCapabilityExecuteResult> {
if (!input.member) {
return { ok: false, error: "forbidden", message: "No active org membership for this token." }
}
let connection: Awaited<ReturnType<typeof getExternalMcpConnection>>
let connectionId: DenTypeId<"externalMcpConnection">
try {
connectionId = normalizeDenTypeId("externalMcpConnection", input.connectionId)
connection = await getExternalMcpConnection({
organizationId: normalizeDenTypeId("organization", input.organizationId),
connectionId,
})
} catch {
// A malformed connectionId (e.g. hand-typed by an agent) isn't a server
// error — it's the same "no such capability" outcome as a valid-shaped
// but nonexistent id, so surface the same clean error either way.
connection = null
connectionId = input.connectionId as DenTypeId<"externalMcpConnection">
}
if (!connection) {
return { ok: false, error: "unknown_capability", message: `No external MCP connection "${input.connectionId}" in this organization.` }
}
if (connection.kind !== "external_mcp") {
return { ok: false, error: "unknown_capability", message: `Connection "${input.connectionId}" is a native provider connector and does not expose MCP tools.` }
}
const canUse = await memberCanUseExternalMcpConnection({
connectionId,
orgMembershipId: input.member.orgMembershipId,
teamIds: input.member.teamIds,
})
if (!canUse) {
return { ok: false, error: "forbidden", message: `You have not been granted access to "${connection.name}".` }
}
const policyDecision = evaluateToolPolicy(connection.toolPolicy, input.toolName)
if (policyDecision.blocked) {
return {
ok: false,
error: "policy_blocked",
capability: buildExternalCapabilityName(connectionId, input.toolName),
message: `${input.toolName} is disabled for your organization${policyDecision.disabledBy ? ` by ${policyDecision.disabledBy}` : ""}.`,
sameArgumentsRetryable: false,
retry: { action: "search_capabilities", searchRequired: true },
}
}
if (connection.oauthIssuerReviewRequiredAt) {
const message = `"${connection.name}" is blocked until an organization admin reviews its changed OAuth issuer.`
return {
ok: false,
error: "needs_connection",
message,
connectionStatus: buildExternalConnectionStatus({
connection,
state: "reauth_required",
errorCode: "unauthorized",
message,
actionOwner: "organization_admin",
}),
}
}
if (input.toolName === "*") {
const message = `"${connection.name}" was surfaced as a connection status entry, not a callable tool. Fix the connection first (see the search hint), then search again for its real tools.`
return {
ok: false,
error: "needs_connection",
message,
connectionStatus: buildExternalConnectionStatus({ connection, state: "needs_connection", errorCode: "not_connected", message }),
}
}
let member: { orgMembershipId: DenTypeId<"member"> } | undefined
if (connection.credentialMode === "per_member") {
const account = await getConnectedAccount({
organizationId: connection.organizationId,
orgMembershipId: input.member.orgMembershipId,
providerId: connection.id,
})
if (!account?.accessToken) {
return {
ok: false,
error: "needs_connection",
message: `You haven't connected your ${connection.name} account yet. Open OmniRush.ai Cloud -> Your Connections and click Connect on "${connection.name}".`,
connectionStatus: buildExternalConnectionStatus({
connection,
state: "needs_connection",
errorCode: "not_connected",
message: `You haven't connected your ${connection.name} account yet.`,
}),
}
}
member = { orgMembershipId: input.member.orgMembershipId }
} else if (!hasSharedCredential(connection)) {
const message = `"${connection.name}" is not connected yet.`
return {
ok: false,
error: "connection_not_connected",
message,
connectionStatus: buildExternalConnectionStatus({ connection, state: "needs_connection", errorCode: "not_connected", message }),
}
}
let currentSchemaDigest: string | undefined
let schemaGuidance: ExternalMcpSchemaGuidance | undefined
const deadline = createExternalMcpLifecycleDeadline(EXTERNAL_MCP_TOOL_LIFECYCLE_TIMEOUT_MS)
try {
const redirectUri = redirectUriFor(input.redirectUriBase, connection.id)
const tools = await listExternalMcpTools(connection, redirectUri, member, undefined, deadline)
const tool = tools.find((candidate) => candidate.name === input.toolName)
if (!tool) {
return {
ok: false,
error: "unknown_capability",
capability: buildExternalCapabilityName(connection.id, input.toolName),
message: `No current tool named "${input.toolName}" exists on "${connection.name}". Call search_capabilities again.`,
sameArgumentsRetryable: false,
retry: { action: "search_capabilities", searchRequired: true },
}
}
if (input.requireReadOnly && (tool.annotations?.readOnlyHint !== true || tool.annotations?.destructiveHint === true)) {
return {
ok: false,
error: "policy_blocked",
capability: buildExternalCapabilityName(connection.id, input.toolName),
message: `${input.toolName} is no longer advertised as strictly read-only, so OmniRush.ai blocked the Remote MCP App call.`,
sameArgumentsRetryable: false,
retry: { action: "search_capabilities", searchRequired: true },
}
}
const schemaDigest = externalMcpToolSchemaDigest(tool.inputSchema)
currentSchemaDigest = schemaDigest
if (input.requireSchemaMatch && input.schemaDigest && input.schemaDigest !== schemaDigest) {
return {
ok: false,
error: "policy_blocked",
capability: buildExternalCapabilityName(connection.id, input.toolName),
message: `${input.toolName} now advertises a different input schema, so OmniRush.ai blocked the Remote MCP App call until its cached revision is refreshed.`,
sameArgumentsRetryable: false,
retry: { action: "search_capabilities", searchRequired: true },
}
}
const schemaWarnings: ExternalMcpSchemaWarning[] = []
if (input.schemaDigest && input.schemaDigest !== schemaDigest) {
schemaWarnings.push({
code: "capability_schema_changed",
message: "The provider advertised a different capability schema after discovery, but OmniRush.ai still forwarded the call.",
searchedSchemaDigest: input.schemaDigest,
currentSchemaDigest: schemaDigest,
suggestedAction: "If the provider call failed, call search_capabilities again and retry with the latest argumentsSchema. Do not retry solely because of this warning when the provider call succeeded.",
})
}
// MCP tool arguments are always an object at the protocol boundary. Start
// the provider call before advisory validation so a provider with an
// inaccurate or unsupported advertised schema still gets the request.
const forwardedArguments = isRecord(input.args) ? input.args : {}
const providerCall = callExternalMcpTool({
connection,
redirectUri,
toolName: input.toolName,
args: forwardedArguments,
member,
lifecycleDeadline: deadline,
})
const validation = validateExternalMcpToolArguments(tool.inputSchema, input.args)
if (!validation.ok && validation.error === "invalid_arguments") {
schemaWarnings.push({
code: "arguments_schema_mismatch",
message: "The arguments do not match the provider's advertised argumentsSchema, but OmniRush.ai still forwarded the call because the provider may accept them.",
issues: validation.issues,
suggestedAction: "If the provider call failed, correct the listed issues and retry with changed arguments. Do not retry solely because of this warning when the provider call succeeded.",
})
} else if (!validation.ok) {
schemaWarnings.push({
code: "arguments_schema_unavailable",
message: validation.message,
suggestedAction: "Use the provider result as the source of truth. If the call failed, the provider administrator may need to repair the advertised inputSchema.",
})
}
schemaGuidance = advisorySchemaGuidance(schemaWarnings)
const result = await providerCall
const resourceUri = externalMcpAppResourceUri(tool)
return {
ok: true,
result,
...(schemaGuidance ? { schemaGuidance } : {}),
...(resourceUri
? {
mcpApp: {
connectionId: connection.id,
toolName: tool.name,
resourceUri,
arguments: forwardedArguments,
},
}
: {}),
}
} catch (error) {
const message = upstreamErrorMessage(error)
const authErrorCode = externalMcpAuthErrorCode(error, message)
if (error instanceof ExternalMcpDiagnosticError) {
const diagnostic = error.diagnostic.code === "MCP_PROVIDER_AUTH_REQUIRED"
? providerAuthorizationDiagnosticForConnection({ diagnostic: error.diagnostic, connectionUrl: connection.url })
: error.diagnostic
const log = externalMcpDiagnosticForLog(error, error.diagnostic.referenceId, "MCP_TOOL_EXECUTION")
console.error("external_mcp_capability_execute_failed", {
connectionId: connection.id,
organizationId: connection.organizationId,
connectionEndpoint: safeExternalMcpEndpointForLog(connection.url),
...log,
diagnostic,
})
if (diagnostic.code === "MCP_INVALID_PARAMS" || diagnostic.code === "MCP_PROVIDER_INVALID_PARAMS") {
return invalidCapabilityArguments({
capability: buildExternalCapabilityName(connection.id, input.toolName),
schemaDigest: currentSchemaDigest ?? input.schemaDigest,
diagnostic,
schemaGuidance,
})
}
if (diagnostic.code === "MCP_PROVIDER_AUTH_REQUIRED") {
const resultMessage = diagnosticAgentMessage(diagnostic)
return {
ok: false,
error: "needs_connection",
message: resultMessage,
...diagnosticAgentFields(diagnostic),
connectionStatus: providerAuthorizationConnectionStatus({
connection,
diagnostic,
message: resultMessage,
}),
...(schemaGuidance ? { schemaGuidance } : {}),
}
}
return {
ok: false,
error: diagnostic.phase === "PROVIDER_EXECUTION" || diagnostic.phase === "PROVIDER_AUTHORIZATION"
? "provider_error"
: "connection_failed",
message: diagnosticAgentMessage(diagnostic),
...diagnosticAgentFields(diagnostic),
...(schemaGuidance ? { schemaGuidance } : {}),
...(authErrorCode
? {
connectionStatus: buildExternalConnectionStatus({
connection,
state: "reauth_required",
errorCode: authErrorCode,
message,
diagnostic,
}),
}
: {}),
}
}
if (authErrorCode) {
return {
ok: false,
error: "connection_failed",
message,
...(schemaGuidance ? { schemaGuidance } : {}),
connectionStatus: buildExternalConnectionStatus({
connection,
state: "reauth_required",
errorCode: authErrorCode,
message,
}),
}
}
throw error
}
}