API: @loopstack/mcp-module

Classes

McpAuthError

Error thrown when the remote MCP server responds with 401 or 403. Catch this to handle missing or invalid authentication credentials.


import { McpAuthError } from '@loopstack/mcp-module';


export class McpAuthError extends McpError {
}

McpCallTool

Tool that calls a tool on a remote MCP server over HTTPS (Streamable HTTP or legacy SSE).


import { McpCallTool } from '@loopstack/mcp-module';

Provided by: McpModule


export class McpCallTool extends McpToolBase<McpCallToolArgs> {
    protected handle(args: McpCallToolArgs, ctx: RunContext, options?: ToolCallOptions<McpToolConfig>): Promise<ToolEnvelope>;
}

McpClientService

Service that connects to remote MCP servers; inject it to list and call tools on an MCP endpoint.


import { McpClientService } from '@loopstack/mcp-module';

Provided by: McpModule


export class McpClientService {
    constructor(env?: EnvReader, metrics?: McpMetricsPort);
    listTools(rawUrl: string, config: McpToolConfig, options?: McpClientCallOptions): Promise<{
        tools: unknown;
    }>;
    callTool(rawUrl: string, config: McpToolConfig, toolName: string, toolArgs: Record<string, unknown>, options?: McpClientCallOptions): Promise<McpCallToolResult>;
    mergeHeaders(config: McpToolConfig, url: URL): Record<string, string>;
}

McpError

Base class for all MCP failures. Catch this to handle any error raised while connecting to or calling a remote MCP server.


import { McpError } from '@loopstack/mcp-module';


export abstract class McpError extends Error {
    constructor(message: string);
}

McpListToolsTool

Tool that lists the tool definitions exposed by a remote MCP server.


import { McpListToolsTool } from '@loopstack/mcp-module';

Provided by: McpModule


export class McpListToolsTool extends McpToolBase<McpListToolsArgs> {
    protected handle(args: McpListToolsArgs, ctx: RunContext, options?: ToolCallOptions<McpToolConfig>): Promise<ToolEnvelope>;
}

McpModule

NestJS module that provides remote MCP client tools — mcp_list_tools (McpListToolsTool), mcp_call (McpCallTool), and the McpClientService that connects to remote Model Context Protocol servers.

Registration:

McpModule.forRoot(McpToolConfigInput) — the only entry point; registers the module globally and co-imports LoopCoreModule. Pass config (allowlist, auth header mappings) to apply it to every tool call; config is optional here, in which case each call must supply config via options.config.

Requires: an allowedHosts allowlist supplied either at the module level (via forRoot) or per call via options.config — a tool call with no config at either level throws (the SSRF allowlist is mandatory). For authenticated servers, the env vars referenced by hostHeaderEnv / headerEnv must also be set, since header values are read from process.env at call time.


import { McpModule } from '@loopstack/mcp-module';


export class McpModule {
    static forRoot(config?: McpToolConfigInput): DynamicModule;
}

McpProtocolError

Error thrown when the MCP server returns a malformed response (JSON-RPC parse or invalid message). Catch this to handle protocol-level violations from the remote server.


import { McpProtocolError } from '@loopstack/mcp-module';


export class McpProtocolError extends McpError {
}

McpTimeoutError

Error thrown when an MCP call exceeds its configured timeoutMs. Catch this to handle slow or unresponsive remote servers.


import { McpTimeoutError } from '@loopstack/mcp-module';


export class McpTimeoutError extends McpError {
}

McpToolBase

Abstract base for tools that call a remote MCP server; extend it to add custom MCP-backed tools.

Concrete subclasses must repeat the @Tool({ schema, configSchema }) decorator — decorator metadata is not inherited.


import { McpToolBase } from '@loopstack/mcp-module';


export abstract class McpToolBase<TArgs extends object> extends BaseTool<TArgs, McpToolConfig> {
    protected readonly mcp: McpClientService;
    protected requireConfig(config: McpToolConfig | undefined): McpToolConfig;
}

McpTransportError

Error thrown on transport-level failures (DNS, TCP, TLS, abort, or transport fallback). Catch this to handle network or connection problems reaching the remote server.


import { McpTransportError } from '@loopstack/mcp-module';


export class McpTransportError extends McpError {
}

McpUrlSecurityError

Error thrown when an MCP URL fails the security checks (SSRF, allowlist, scheme, or userinfo violations). Catch this to react to a rejected or unsafe target URL.


import { McpUrlSecurityError } from '@loopstack/mcp-module';


export class McpUrlSecurityError extends McpError {
}

Interfaces

McpClientCallOptions

Options for an McpClientService call (per-request timeout, transport, DNS-resolution skip).


import { McpClientCallOptions } from '@loopstack/mcp-module';


export interface McpClientCallOptions {
    timeoutMs?: number;
    skipDnsResolution?: boolean;
    transport?: McpTransportKind;
}

Type Aliases

McpCallToolArgs

Args for McpCallTool (mcp_call).


import { McpCallToolArgs } from '@loopstack/mcp-module';


export type McpCallToolArgs = z.infer<typeof McpCallToolArgsSchema>;

McpCallToolResult

Result of an McpClientService.callTool() invocation — a modern call-tool result or a legacy tool result.


import { McpCallToolResult } from '@loopstack/mcp-module';


export type McpCallToolResult = {
    kind: 'legacyToolResult';
    toolResult: unknown;
    meta?: unknown;
} | {
    kind: 'callToolResult';
    content: unknown;
    structuredContent?: unknown;
    isError?: unknown;
    meta?: unknown;
};

McpConnectionArgs

Args for connecting to a remote MCP server, shared by the MCP tools.


import { McpConnectionArgs } from '@loopstack/mcp-module';


export type McpConnectionArgs = z.infer<typeof McpConnectionArgsSchema>;

McpListToolsArgs

Args for McpListToolsTool (mcp_list_tools).


import { McpListToolsArgs } from '@loopstack/mcp-module';


export type McpListToolsArgs = z.infer<typeof McpListToolsArgsSchema>;

McpToolConfig

Config for the MCP tools (McpCallTool, McpListToolsTool).


import { McpToolConfig } from '@loopstack/mcp-module';


export type McpToolConfig = z.infer<typeof McpToolConfigSchema>;

McpToolConfigInput

Input config for McpModule.forRoot() (the pre-parse shape of McpToolConfig).


import { McpToolConfigInput } from '@loopstack/mcp-module';


export type McpToolConfigInput = z.input<typeof McpToolConfigSchema>;

McpTransportKind

Transport used to reach a remote MCP server — Streamable HTTP or legacy SSE.


import { McpTransportKind } from '@loopstack/mcp-module';


export type McpTransportKind = 'streamableHttp' | 'sse';

Variables

McpCallToolArgsSchema

Zod schema for mcp_call tool arguments.


import { McpCallToolArgsSchema } from '@loopstack/mcp-module';


McpCallToolArgsSchema: z.ZodObject<{
    serverUrl: z.ZodURL;
    timeoutMs: z.ZodOptional<z.ZodNumber>;
    transport: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
        streamableHttp: "streamableHttp";
        sse: "sse";
    }>>>;
    toolName: z.ZodString;
    arguments: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
}, z.core.$strict>

McpConnectionArgsSchema

Zod schema for the connection arguments shared by the MCP tools (serverUrl, timeoutMs, transport).


import { McpConnectionArgsSchema } from '@loopstack/mcp-module';


McpConnectionArgsSchema: z.ZodObject<{
    serverUrl: z.ZodURL;
    timeoutMs: z.ZodOptional<z.ZodNumber>;
    transport: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
        streamableHttp: "streamableHttp";
        sse: "sse";
    }>>>;
}, z.core.$strict>

McpListToolsArgsSchema

Zod schema for mcp_list_tools tool arguments.


import { McpListToolsArgsSchema } from '@loopstack/mcp-module';


McpListToolsArgsSchema: z.ZodObject<{
    serverUrl: z.ZodURL;
    timeoutMs: z.ZodOptional<z.ZodNumber>;
    transport: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
        streamableHttp: "streamableHttp";
        sse: "sse";
    }>>>;
}, z.core.$strict>

McpToolConfigSchema

Zod schema for MCP tool configuration — host allowlist and auth header mappings.


import { McpToolConfigSchema } from '@loopstack/mcp-module';


McpToolConfigSchema: z.ZodObject<{
    allowedHosts: z.ZodArray<z.ZodString>;
    allowInsecureHttp: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
    allowPrivateHosts: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
    defaultHeaders: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
    headerEnv: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
    hostHeaderEnv: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>>>;
}, z.core.$strict>