Remote Errors

Errors for remote MCP server connections, operations, and configuration.

Overview

Remote errors are thrown when interacting with remote MCP servers via the @App() decorator’s remote app configuration. They cover connection failures, timeouts, not-found resources, auth issues, execution failures, transport problems, capability mismatches, configuration errors, and retry validation.

Connection Errors

RemoteConnectionError

Thrown when the initial connection to a remote MCP server fails.

Property	Type	Value
code	string	REMOTE_CONNECTION_ERROR
statusCode	number	500
isPublic	boolean	false
appId	string	Remote app identifier
url	string	Target URL
originalError	Error | undefined	The underlying cause

new RemoteConnectionError(appId: string, url: string, originalError?: Error)

---

RemoteDisconnectError

Thrown when a remote MCP server disconnects unexpectedly.

Property	Type	Value
code	string	REMOTE_DISCONNECT_ERROR
statusCode	number	500
isPublic	boolean	false
appId	string	Remote app identifier
reason	string | undefined	Disconnect reason

new RemoteDisconnectError(appId: string, reason?: string)

Timeout Errors

RemoteTimeoutError

Thrown when a remote MCP operation exceeds the configured timeout.

Property	Type	Value
code	string	REMOTE_TIMEOUT_ERROR
statusCode	number	504
isPublic	boolean	true
appId	string	Remote app identifier
operation	string	The operation that timed out
timeoutMs	number	Configured timeout
mcpErrorCode	number	-32603

new RemoteTimeoutError(appId: string, operation: string, timeoutMs: number)

Example:

import { RemoteTimeoutError } from '@frontmcp/sdk';

throw new RemoteTimeoutError('slack', 'tools/call', 30000);

Not Found Errors

RemoteToolNotFoundError

Thrown when a tool is not found on the remote server.

Property	Type	Value
code	string	REMOTE_TOOL_NOT_FOUND
statusCode	number	404
isPublic	boolean	true
appId	string	Remote app identifier
toolName	string	The missing tool
mcpErrorCode	number	-32601

new RemoteToolNotFoundError(appId: string, toolName: string)

---

RemoteResourceNotFoundError

Thrown when a resource is not found on the remote server.

Property	Type	Value
code	string	REMOTE_RESOURCE_NOT_FOUND
statusCode	number	404
isPublic	boolean	true
appId	string	Remote app identifier
uri	string	The missing resource URI
mcpErrorCode	number	-32002

new RemoteResourceNotFoundError(appId: string, uri: string)

---

RemotePromptNotFoundError

Thrown when a prompt is not found on the remote server.

Property	Type	Value
code	string	REMOTE_PROMPT_NOT_FOUND
statusCode	number	404
isPublic	boolean	true
appId	string	Remote app identifier
promptName	string	The missing prompt
mcpErrorCode	number	-32601

new RemotePromptNotFoundError(appId: string, promptName: string)

Auth Errors

RemoteAuthError

Thrown when authentication to a remote server fails (missing credentials).

Property	Type	Value
code	string	REMOTE_AUTH_ERROR
statusCode	number	401
isPublic	boolean	true
appId	string	Remote app identifier
details	string | undefined	Additional details
mcpErrorCode	number	-32001

new RemoteAuthError(appId: string, details?: string)

---

RemoteAuthorizationError

Thrown when authorization to a remote resource/tool fails (insufficient credentials).

Property	Type	Value
code	string	REMOTE_AUTHORIZATION_ERROR
statusCode	number	403
isPublic	boolean	true
appId	string	Remote app identifier
resource	string | undefined	The denied resource
mcpErrorCode	number	-32003

new RemoteAuthorizationError(appId: string, resource?: string)

Execution Errors

RemoteToolExecutionError

Thrown when a remote tool execution fails.

Property	Type	Value
code	string	REMOTE_TOOL_EXECUTION_ERROR
statusCode	number	500
isPublic	boolean	true
appId	string	Remote app identifier
toolName	string	The failed tool
originalError	Error | undefined	The underlying cause
mcpErrorCode	number	-32603

new RemoteToolExecutionError(appId: string, toolName: string, originalError?: Error)

---

RemoteResourceReadError

Thrown when reading a remote resource fails.

Property	Type	Value
code	string	REMOTE_RESOURCE_READ_ERROR
statusCode	number	500
isPublic	boolean	true
appId	string	Remote app identifier
uri	string	The resource URI
originalError	Error | undefined	The underlying cause
mcpErrorCode	number	-32603

new RemoteResourceReadError(appId: string, uri: string, originalError?: Error)

---

RemotePromptGetError

Thrown when getting a remote prompt fails.

Property	Type	Value
code	string	REMOTE_PROMPT_GET_ERROR
statusCode	number	500
isPublic	boolean	true
appId	string	Remote app identifier
promptName	string	The prompt name
originalError	Error | undefined	The underlying cause
mcpErrorCode	number	-32603

new RemotePromptGetError(appId: string, promptName: string, originalError?: Error)

Transport Errors

RemoteTransportError

Thrown when transport initialization fails for a remote app.

Property	Type	Value
code	string	REMOTE_TRANSPORT_ERROR
statusCode	number	500
isPublic	boolean	false
appId	string	Remote app identifier
transportType	string	The transport type
originalError	Error | undefined	The underlying cause

new RemoteTransportError(appId: string, transportType: string, originalError?: Error)

---

RemoteUnsupportedTransportError

Thrown when an unsupported transport type is specified for a remote app.

Property	Type	Value
code	string	REMOTE_UNSUPPORTED_TRANSPORT
statusCode	number	400
isPublic	boolean	true
transportType	string	The unsupported type

new RemoteUnsupportedTransportError(transportType: string)

Capability Errors

RemoteCapabilityDiscoveryError

Thrown when capability discovery fails for a remote server.

Property	Type	Value
code	string	REMOTE_CAPABILITY_DISCOVERY_ERROR
statusCode	number	500
isPublic	boolean	false
appId	string	Remote app identifier
originalError	Error | undefined	The underlying cause

new RemoteCapabilityDiscoveryError(appId: string, originalError?: Error)

---

RemoteCapabilityNotSupportedError

Thrown when a remote server doesn’t support a required capability.

Property	Type	Value
code	string	REMOTE_CAPABILITY_NOT_SUPPORTED
statusCode	number	400
isPublic	boolean	true
appId	string	Remote app identifier
capability	string	The missing capability

new RemoteCapabilityNotSupportedError(appId: string, capability: string)

Configuration Errors

RemoteConfigurationError

Thrown when a remote app’s configuration is invalid.

Property	Type	Value
code	string	REMOTE_CONFIGURATION_ERROR
statusCode	number	400
isPublic	boolean	true
appId	string	Remote app identifier
configField	string | undefined	The invalid field
details	string | undefined	Additional details

new RemoteConfigurationError(appId: string, configField?: string, details?: string)

---

RemoteNotConnectedError

Thrown when an operation is attempted on a remote app that is not connected.

Property	Type	Value
code	string	REMOTE_NOT_CONNECTED
statusCode	number	503
isPublic	boolean	true
appId	string	Remote app identifier

new RemoteNotConnectedError(appId: string)

Retry Errors

InvalidRetryOptionsError

Thrown when retry configuration is invalid (e.g., maxAttempts < 1).

Property	Type	Value
code	string	INVALID_RETRY_OPTIONS
statusCode	number	500
isPublic	boolean	false
option	string	The invalid option name
value	unknown	The invalid value

new InvalidRetryOptionsError(option: string, value: unknown, reason: string)

Example:

import { InvalidRetryOptionsError } from '@frontmcp/sdk';

throw new InvalidRetryOptionsError('maxAttempts', 0, 'must be >= 1');