Class MCPConnection

Base MCP connection managing JSON-RPC 2.0 transport over stdio or HTTP gateway. Extended by domain-specific clients to add tool wrapper methods.

Hierarchy (View Summary)

MCPConnection
- WorldBankMCPClient
- EuropeanParliamentMCPClient

Constructors

constructor

new MCPConnection(options?: MCPClientOptions): MCPConnection
Create a new MCP connection.

Resolves the server binary path, gateway URL, and authentication options from the explicit options, then from environment variables, and finally module-level defaults. The connection is not opened until connect is called.
Parameters
- options: MCPClientOptions = {}
  Connection options including server path, gateway URL, API key, retry policy, and human-readable server label for log messages.
Returns MCPConnection
- Defined in mcp/transport/connection.ts:74

Methods

isConnected

isConnected(): boolean
Check if client is connected

Returns boolean
Connection status
- Defined in mcp/transport/connection.ts:101

isGatewayMode

isGatewayMode(): boolean
Check if using gateway HTTP transport

Returns boolean
True if gateway mode is active
- Defined in mcp/transport/connection.ts:110

getGatewayUrl

getGatewayUrl(): string | null
Get the configured gateway URL

Returns string | null
Gateway URL or null if using stdio transport
- Defined in mcp/transport/connection.ts:119

getGatewayApiKey

getGatewayApiKey(): string | null
Get the configured gateway API key

Returns string | null
Gateway API key or null if not set
- Defined in mcp/transport/connection.ts:128

getMcpSessionId

getMcpSessionId(): string | null
Get the current MCP session ID

Returns string | null
Session ID returned by the gateway, or null if not yet connected
- Defined in mcp/transport/connection.ts:137

getConnectionHealth

getConnectionHealth(): {
    timeoutCount: number;
    reconnectCount: number;
    connected: boolean;
}
Get connection health metrics for telemetry

Returns { timeoutCount: number; reconnectCount: number; connected: boolean }
Object with timeout count, reconnection count, and current connection status
- Defined in mcp/transport/connection.ts:146

connect

connect(): Promise<void>
Connect to the MCP server with retry logic

Returns Promise<void>
- Defined in mcp/transport/connection.ts:157

`Private`_nextConnectionDelay

_nextConnectionDelay(error: unknown): number
Advance the attempt counter and compute the next retry delay. Throws immediately for non-retriable errors or when exhausted.
Parameters
- error: unknown
  The error from the failed attempt
Returns number
Delay in milliseconds to wait before the next attempt
- Defined in mcp/transport/connection.ts:196

`Private`_gatewayContext

_gatewayContext(): GatewayContext
Build a GatewayContext adapter for gateway.ts helpers.

Returns GatewayContext
Context adapter for gateway.ts helpers
- Defined in mcp/transport/connection.ts:218

`Private`_spawnContext

_spawnContext(): SpawnContext
Build a SpawnContext adapter for process.ts spawn helpers.

Returns SpawnContext
Context adapter for stdio spawn helpers
- Defined in mcp/transport/connection.ts:239

`Private`_attemptConnection

_attemptConnection(): Promise<void>
Attempt a single connection via stdio (spawns server binary). Delegates to attemptStdioConnection in process.ts.

Returns Promise<void>
Resolves when the spawn has completed (or rejects on spawn failure)
- Defined in mcp/transport/connection.ts:266

disconnect

disconnect(): void
Disconnect from the MCP server

Returns void
- Defined in mcp/transport/connection.ts:273

handleMessage

handleMessage(line: string): void
Handle incoming messages from MCP server (stdio mode only). Delegates to handleIncomingMessage in process.ts.
Parameters
- line: string
  JSON message line from server
Returns void
- Defined in mcp/transport/connection.ts:288

sendRequest

sendRequest<T = unknown>(
method: string,
params?: Record<string, unknown>,
): Promise<T>
Send a request to the MCP server
Type Parameters
- T = unknown
Parameters
- method: string
  RPC method name
- params: Record<string, unknown> = {}
  Method parameters
Returns Promise<T>
Server response
- Defined in mcp/transport/connection.ts:299

listTools

listTools(): Promise<unknown>
List available MCP tools

Returns Promise<unknown>
List of available tools
- Defined in mcp/transport/connection.ts:339

callTool

callTool(name: string, args?: object): Promise<MCPToolResult>
Call an MCP tool
Parameters
- name: string
  Tool name
- args: object = {}
  Tool arguments (must be a plain object, non-null, not an array)
Returns Promise<MCPToolResult>
Tool execution result
- Defined in mcp/transport/connection.ts:350

`Private`_reconnectOps

_reconnectOps(): ReconnectOps
Build a ReconnectOps adapter for reconnect.ts helpers.

Returns ReconnectOps
Context adapter for reconnect/retry helpers
- Defined in mcp/transport/connection.ts:364

reconnect

reconnect(): Promise<void>
Attempt to reconnect to the MCP server. Deduplicates concurrent calls — only one reconnect runs at a time.

Returns Promise<void>
Resolves when reconnect succeeds or all attempts are exhausted
- Defined in mcp/transport/connection.ts:396

callToolWithRetry

callToolWithRetry(
    name: string,
    args?: object,
    maxRetries?: number,
): Promise<MCPToolResult>
Call an MCP tool with automatic retry on timeout or connection loss. Reconnects automatically if the connection was lost between attempts.

Only transient failures are retried (see isRetriableError). Non-retriable errors — rate-limit (429), session-expired (401), and programmer errors such as TypeError — are re-thrown immediately without consuming any retry budget.
Parameters
- name: string
  Tool name
- args: object = {}
  Tool arguments (plain object, non-null, not an array)
- OptionalmaxRetries: number
  Override the default retry count from options
Returns Promise<MCPToolResult>
Tool execution result
- Defined in mcp/transport/connection.ts:413

Properties

`Private`serverPath

serverPath: string

`Private`connected

connected: boolean

`Private`process

process: ChildProcess | null

`Private`requestId

requestId: number

`Private`pendingRequests

pendingRequests: Map<number, PendingRequest>

`Private`connectionAttempts

connectionAttempts: number

`Private`maxConnectionAttempts

maxConnectionAttempts: number

`Private`connectionRetryDelay

connectionRetryDelay: number

`Private`maxRetries

maxRetries: number

`Private`reconnectingPromise

reconnectingPromise: Promise<void> | null

`Private`timeoutCount

timeoutCount: number

`Private`reconnectCount

reconnectCount: number

`Private`gatewayUrl

gatewayUrl: string | null

Gateway URL for HTTP transport mode

`Private`gatewayApiKey

gatewayApiKey: string | null

API key for gateway authentication

`Private`mcpSessionId

mcpSessionId: string | null

MCP session ID returned by the gateway

`Protected`serverLabel

serverLabel: string

Human-readable server name for log messages

Class MCPConnection

Hierarchy (View Summary)

Index

Constructors

Methods

Properties

Constructors

constructor

Parameters

Returns MCPConnection

Methods

isConnected

Returns boolean

isGatewayMode

Returns boolean

getGatewayUrl

Returns string | null

getGatewayApiKey

Returns string | null

getMcpSessionId

Returns string | null

getConnectionHealth

Returns { timeoutCount: number; reconnectCount: number; connected: boolean }

connect

Returns Promise<void>

Private_nextConnectionDelay

Parameters

Returns number

Private_gatewayContext

Returns GatewayContext

Private_spawnContext

Returns SpawnContext

Private_attemptConnection

Returns Promise<void>

disconnect

Returns void

handleMessage

Parameters

Returns void

sendRequest

Type Parameters

Parameters

Returns Promise<T>

listTools

Returns Promise<unknown>

callTool

Parameters

Returns Promise<MCPToolResult>

Private_reconnectOps

Returns ReconnectOps

reconnect

Returns Promise<void>

callToolWithRetry

Parameters

Returns Promise<MCPToolResult>

Properties

PrivateserverPath

Privateconnected

Privateprocess

PrivaterequestId

PrivatependingRequests

PrivateconnectionAttempts

PrivatemaxConnectionAttempts

PrivateconnectionRetryDelay

PrivatemaxRetries

PrivatereconnectingPromise

PrivatetimeoutCount

PrivatereconnectCount

PrivategatewayUrl

PrivategatewayApiKey

PrivatemcpSessionId

ProtectedserverLabel

Settings

On This Page

`Private`_nextConnectionDelay

`Private`_gatewayContext

`Private`_spawnContext

`Private`_attemptConnection

`Private`_reconnectOps

`Private`serverPath

`Private`connected

`Private`process

`Private`requestId

`Private`pendingRequests

`Private`connectionAttempts

`Private`maxConnectionAttempts

`Private`connectionRetryDelay

`Private`maxRetries

`Private`reconnectingPromise

`Private`timeoutCount

`Private`reconnectCount

`Private`gatewayUrl

`Private`gatewayApiKey

`Private`mcpSessionId

`Protected`serverLabel