API: @loopstack/mcp

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';

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';

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';

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';

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';

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';

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';

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';

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';

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';

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';

export class McpUrlSecurityError extends McpError {}

Interfaces

McpClientCallOptions

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

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

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

Type Aliases

McpCallToolArgs

Args for McpCallTool (mcp_call).

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

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';

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';

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

McpListToolsArgs

Args for McpListToolsTool (mcp_list_tools).

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

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

McpToolConfig

Config for the MCP tools (McpCallTool, McpListToolsTool).

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

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

McpToolConfigInput

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

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

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';

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

Variables

McpCallToolArgsSchema

Zod schema for mcp_call tool arguments.

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

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
>;

McpCallToolResultSchema

Zod schema for McpCallToolResult — the resultSchema of mcp_call. The proxied tool payloads (toolResult, content, structuredContent, meta) are intentionally uncontracted.

import { McpCallToolResultSchema } from '@loopstack/mcp';

McpCallToolResultSchema: z.ZodUnion<
  readonly [
    z.ZodObject<
      {
        kind: z.ZodLiteral<'legacyToolResult'>;
        toolResult: z.ZodUnknown;
        meta: z.ZodOptional<z.ZodUnknown>;
      },
      z.core.$strict
    >,
    z.ZodObject<
      {
        kind: z.ZodLiteral<'callToolResult'>;
        content: z.ZodUnknown;
        structuredContent: z.ZodOptional<z.ZodUnknown>;
        isError: z.ZodOptional<z.ZodUnknown>;
        meta: z.ZodOptional<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';

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';

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
>;

McpListToolsResultSchema

Zod schema for the mcp_list_tools result — the remote server’s tool definitions are passed through verbatim and intentionally uncontracted.

import { McpListToolsResultSchema } from '@loopstack/mcp';

McpListToolsResultSchema: z.ZodObject<
  {
    tools: z.ZodUnknown;
  },
  z.core.$strict
>;

McpToolConfigSchema

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

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

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
>;