MCP

@typia/mcp registers typia controllers as Model Context Protocol tools. Every method on your TypeScript class — or every endpoint in an OpenAPI document — becomes an MCP tool, with the same parse/coerce/validate/feedback machinery as typia.llm.application wired in automatically.

signature


import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { registerMcpControllers } from "@typia/mcp";
 
export function registerMcpControllers(props: {
  server: McpServer | Server;
  controllers: Array<ILlmController | IHttpLlmController>;
  preserve?: boolean;
}): void;

Argument	Meaning
`server`	An MCP server instance (`McpServer` or raw `Server` from the MCP SDK)
`controllers`	An array of controllers — either `typia.llm.controller<Class>()` or `HttpLlm.controller()`
`preserve`	`false` (default): typia owns the server’s tool list. `true`: coexist with the MCP SDK’s `McpServer.registerTool()` calls.

undefined

@typia/mcp


export function registerMcpControllers(props: {
  server: McpServer | Server;
  controllers: Array<ILlmController | IHttpLlmController>;
  preserve?: boolean | undefined;
}): void;

undefined

@typia/interface


import { ILlmApplication } from "./ILlmApplication";
 
/**
 * Controller of TypeScript class-based LLM function calling.
 *
 * `ILlmController` is a controller for registering TypeScript class methods as
 * LLM function calling tools. It contains {@link ILlmApplication} with
 * {@link ILlmFunction function calling schemas}, {@link name identifier}, and
 * {@link execute class instance} for method execution.
 *
 * You can create this controller with `typia.llm.controller<Class>()` function,
 * and register it to MCP server with {@link registerMcpControllers}:
 *
 * ```typescript
 * import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 * import { registerMcpControllers } from "@typia/mcp";
 * import typia from "typia";
 *
 * class Calculator {
 *   add(input: { a: number; b: number }): number {
 *     return input.a + input.b;
 *   }
 *   subtract(input: { a: number; b: number }): number {
 *     return input.a - input.b;
 *   }
 * }
 *
 * const server = new McpServer({ name: "my-server", version: "1.0.0" });
 * registerMcpControllers({
 *   server,
 *   controllers: [
 *     typia.llm.controller<Calculator>("calculator", new Calculator()),
 *   ],
 * });
 * ```
 *
 * For OpenAPI/HTTP-based controller, use {@link IHttpLlmController} instead.
 *
 * @author Jeongho Nam - https://github.com/samchon
 * @template Class Class type of the function executor
 */
export interface ILlmController<Class extends object = any> {
  /** Protocol discriminator. */
  protocol: "class";
 
  /** Identifier name of the controller. */
  name: string;
 
  /** Application schema of function calling. */
  application: ILlmApplication<Class>;
 
  /** Target class instance for function execution. */
  execute: Class;
}

undefined

@typia/interface


import { IHttpConnection } from "./IHttpConnection";
import { IHttpLlmApplication } from "./IHttpLlmApplication";
import { IHttpLlmFunction } from "./IHttpLlmFunction";
import { IHttpResponse } from "./IHttpResponse";
 
/**
 * Controller of HTTP LLM function calling.
 *
 * `IHttpLlmController` is a controller for registering OpenAPI operations as
 * LLM function calling tools. It contains {@link IHttpLlmApplication} with
 * {@link IHttpLlmFunction function calling schemas}, {@link name identifier}, and
 * {@link connection} to the API server.
 *
 * You can create this controller with {@link HttpLlm.controller} function, and
 * register it to MCP server with {@link registerMcpControllers}:
 *
 * ```typescript
 * import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 * import { registerMcpControllers } from "@typia/mcp";
 * import { HttpLlm } from "@typia/utils";
 *
 * const server = new McpServer({ name: "my-server", version: "1.0.0" });
 * registerMcpControllers({
 *   server,
 *   controllers: [
 *     HttpLlm.controller({
 *       name: "shopping",
 *       document: await fetch(
 *         "https://shopping-be.wrtn.io/editor/swagger.json",
 *       ).then((r) => r.json()),
 *       connection: {
 *         host: "https://shopping-be.wrtn.io",
 *         headers: {
 *           Authorization: "Bearer ********",
 *         },
 *       },
 *     }),
 *   ],
 * });
 * ```
 *
 * For TypeScript class-based controller, use {@link ILlmController} instead.
 *
 * @author Jeongho Nam - https://github.com/samchon
 */
export interface IHttpLlmController {
  /** Protocol discriminator. */
  protocol: "http";
 
  /** Identifier name of the controller. */
  name: string;
 
  /** Application schema of function calling. */
  application: IHttpLlmApplication;
 
  /**
   * Connection to the server.
   *
   * Connection to the API server including the URL and headers.
   */
  connection: IHttpConnection;
 
  /**
   * Executor of the API function.
   *
   * Default executor is {@link HttpLlm.execute} function, and you can override
   * it with your own function.
   *
   * @param props Properties of the API function call
   * @returns HTTP response of the API function call
   */
  execute?:
    | undefined
    | ((props: {
        /** Connection to the server. */
        connection: IHttpConnection;
 
        /** Application schema. */
        application: IHttpLlmApplication;
 
        /** Function schema. */
        function: IHttpLlmFunction;
 
        /**
         * Arguments of the function calling.
         *
         * It is an object of key-value pairs of the API function's parameters.
         * The property keys are composed by below rules:
         *
         * - Parameter names
         * - Query parameter as an object type if exists
         * - Body parameter if exists
         */
        arguments: object;
      }) => Promise<IHttpResponse>);
}

undefined

@typia/utils


import {
  IHttpConnection,
  IHttpLlmApplication,
  IHttpLlmController,
  IHttpLlmFunction,
  IHttpMigrateApplication,
  IHttpResponse,
  OpenApi,
  OpenApiV3,
  OpenApiV3_1,
  OpenApiV3_2,
  SwaggerV2,
} from "@typia/interface";
 
import { HttpMigration } from "./HttpMigration";
import { HttpLlmApplicationComposer } from "./internal/HttpLlmApplicationComposer";
import { HttpLlmFunctionFetcher } from "./internal/HttpLlmFunctionFetcher";
 
/**
 * LLM function calling utilities for OpenAPI documents.
 *
 * `HttpLlm` converts OpenAPI documents into LLM function calling applications
 * and executes them. Supports all OpenAPI versions (Swagger 2.0, OpenAPI 3.0,
 * 3.1) through automatic conversion to {@link OpenApi} format.
 *
 * Main functions:
 *
 * - {@link controller}: Create {@link IHttpLlmController} from OpenAPI document
 * - {@link application}: Convert OpenAPI document to {@link IHttpLlmApplication}
 * - {@link execute}: Call an LLM function and return the response body
 * - {@link propagate}: Call an LLM function and return full HTTP response
 * - {@link mergeParameters}: Merge LLM-filled and human-filled parameters
 *
 * Typical workflow:
 *
 * 1. Load OpenAPI document (JSON/YAML)
 * 2. Call `HttpLlm.application()` to get function schemas
 * 3. Send function schemas to LLM for function selection
 * 4. Call `HttpLlm.execute()` with LLM's chosen function and arguments
 *
 * @author Jeongho Nam - https://github.com/samchon
 */
export namespace HttpLlm {
  /* -----------------------------------------------------------
    COMPOSERS
  ----------------------------------------------------------- */
  /**
   * Create HTTP LLM controller from OpenAPI document.
   *
   * Composes {@link IHttpLlmController} from OpenAPI document with connection
   * info. The controller can be used with {@link registerMcpControllers} to
   * register all API operations as MCP tools at once.
   *
   * @param props Controller properties
   * @returns HTTP LLM controller
   */
  export const controller = (props: {
    /** Identifier name of the controller. */
    name: string;
 
    /** OpenAPI document to convert. */
    document:
      | OpenApi.IDocument
      | SwaggerV2.IDocument
      | OpenApiV3.IDocument
      | OpenApiV3_1.IDocument
      | OpenApiV3_2.IDocument;
 
    /** Connection to the API server. */
    connection: IHttpConnection;
 
    /** LLM schema conversion configuration. */
    config?: Partial<IHttpLlmApplication.IConfig>;
 
    /**
     * Custom executor of the API function.
     *
     * Default executor is {@link HttpLlm.execute} function.
     */
    execute?: IHttpLlmController["execute"];
  }): IHttpLlmController => ({
    protocol: "http",
    name: props.name,
    application: application({
      document: props.document,
      config: props.config,
    }),
    connection: props.connection,
    execute: props.execute,
  });
 
  /**
   * Convert OpenAPI document to LLM function calling application.
   *
   * Converts API operations to LLM-callable functions.
   *
   * @param props Composition properties
   * @returns LLM function calling application
   */
  export const application = (props: {
    /** OpenAPI document to convert. */
    document:
      | OpenApi.IDocument
      | SwaggerV2.IDocument
      | OpenApiV3.IDocument
      | OpenApiV3_1.IDocument
      | OpenApiV3_2.IDocument;
 
    /** LLM schema conversion configuration. */
    config?: Partial<IHttpLlmApplication.IConfig>;
  }): IHttpLlmApplication => {
    // MIGRATE
    const migrate: IHttpMigrateApplication = HttpMigration.application(
      props.document,
    );
    return HttpLlmApplicationComposer.application({
      migrate,
      config: {
        strict: props.config?.strict ?? false,
        maxLength: props.config?.maxLength ?? 64,
        equals: props.config?.equals ?? false,
      },
    });
  };
 
  /* -----------------------------------------------------------
    FETCHERS
  ----------------------------------------------------------- */
  /** Properties for LLM function call. */
  export interface IFetchProps {
    /** LLM function calling application. */
    application: IHttpLlmApplication;
 
    /** Function to call. */
    function: IHttpLlmFunction;
 
    /** HTTP connection info. */
    connection: IHttpConnection;
 
    /** Function arguments. */
    input: object;
  }
 
  /**
   * Execute LLM function call.
   *
   * Calls API endpoint and returns response body. Throws {@link HttpError} on
   * non-2xx status.
   *
   * @param props Function call properties
   * @returns Response body
   * @throws HttpError on non-2xx status
   */
  export const execute = (props: IFetchProps): Promise<unknown> =>
    HttpLlmFunctionFetcher.execute(props);
 
  /**
   * Propagate LLM function call.
   *
   * Calls API endpoint and returns full response including non-2xx. Use when
   * you need to handle error responses yourself.
   *
   * @param props Function call properties
   * @returns Full HTTP response
   * @throws Error only on connection failure
   */
  export const propagate = (props: IFetchProps): Promise<IHttpResponse> =>
    HttpLlmFunctionFetcher.propagate(props);
}

Setup

Terminal


npm install @typia/mcp @modelcontextprotocol/sdk
npm install typia
npx typia setup

From a TypeScript class

src/main.ts


import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { registerMcpControllers } from "@typia/mcp";
import typia from "typia";
 
import { BbsArticleService } from "./BbsArticleService";
import { Calculator } from "./Calculator";
 
const server: McpServer = new McpServer({
  name: "my-server",
  version: "1.0.0",
});
 
registerMcpControllers({
  server,
  controllers: [
    typia.llm.controller<Calculator>("calculator", new Calculator()),
    typia.llm.controller<BbsArticleService>("bbs", new BbsArticleService()),
  ],
});

Every method on Calculator and BbsArticleService becomes an MCP tool. JSDoc comments turn into tool descriptions, TypeScript types turn into JSON schemas. Tool names are {controllerName}_{methodName} (e.g. calculator_add, bbs_create).

undefined

Calculator.ts


export class Calculator {
  /**
   * Add two numbers.
   *
   * @param p The input containing two numbers to add
   * @returns The sum of a and b
   */
  add(p: Calculator.IProps): Calculator.IResult {
    return { value: p.x + p.y };
  }
 
  /**
   * Subtract two numbers.
   *
   * @param p The input containing two numbers to subtract
   * @returns The difference of a and b
   */
  subtract(p: Calculator.IProps): Calculator.IResult {
    return { value: p.x - p.y };
  }
 
  /**
   * Multiply two numbers.
   *
   * @param p The input containing two numbers to multiply
   * @returns The product of a and b
   */
  multiply(p: Calculator.IProps): Calculator.IResult {
    return { value: p.x * p.y };
  }
 
  /**
   * Divide two numbers.
   *
   * @param p The input containing two numbers to divide
   * @returns The quotient of a and b
   */
  divide(p: Calculator.IProps): Calculator.IResult {
    if (p.y === 0) {
      throw new Error("Division by zero is not allowed");
    }
    return { value: p.x / p.y };
  }
}
export namespace Calculator {
  export interface IProps {
    /** First operand */
    x: number;
 
    /** Second operand */
    y: number;
  }
 
  /** Result of a calculation. */
  export interface IResult {
    /** Calculated value */
    value: number;
  }
}

undefined

BbsArticleService.ts


import { tags } from "typia";
 
import { IBbsArticle } from "./IBbsArticle";
 
export declare class BbsArticleService {
  /**
   * Get all articles.
   *
   * List up every articles archived in the BBS DB.
   *
   * @returns List of every articles
   */
  public index(): IBbsArticle.IPage;
 
  /**
   * Create a new article.
   *
   * Writes a new article and archives it into the DB.
   *
   * @param props Properties of create function
   * @returns Newly created article
   */
  public create(props: {
    /** Information of the article to create */
    input: IBbsArticle.ICreate;
  }): IBbsArticle;
 
  /**
   * Update an article.
   *
   * Updates an article with new content.
   *
   * @param props Properties of update function
   * @param input New content to update
   */
  public update(props: {
    /** Target article's {@link IBbsArticle.id}. */
    id: string & tags.Format<"uuid">;
 
    /** New content to update. */
    input: IBbsArticle.IUpdate;
  }): void;
 
  /**
   * Erase an article.
   *
   * Erases an article from the DB.
   *
   * @param props Properties of erase function
   */
  public erase(props: {
    /** Target article's {@link IBbsArticle.id}. */
    id: string & tags.Format<"uuid">;
  }): void;
}

undefined

IBbsArticle.ts


import { tags } from "typia";
 
/**
 * Article entity.
 *
 * `IBbsArticle` is an entity representing an article in the BBS (Bulletin Board
 * System).
 */
export interface IBbsArticle extends IBbsArticle.ICreate {
  /** Primary Key. */
  id: string & tags.Format<"uuid">;
 
  /** Creation time of the article. */
  created_at: string & tags.Format<"date-time">;
 
  /** Last updated time of the article. */
  updated_at: string & tags.Format<"date-time">;
}
export namespace IBbsArticle {
  /** Information of the article to create. */
  export interface ICreate {
    /**
     * Title of the article.
     *
     * Representative title of the article.
     */
    title: string;
 
    /**
     * Content body.
     *
     * Content body of the article written in the markdown format.
     */
    body: string;
 
    /**
     * Thumbnail image URI.
     *
     * Thumbnail image URI which can represent the article.
     *
     * If configured as `null`, it means that no thumbnail image in the article.
     */
    thumbnail:
      | null
      | (string & tags.Format<"uri"> & tags.ContentMediaType<"image/*">);
  }
 
  /**
   * Information of the article to update.
   *
   * Only the filled properties will be updated.
   */
  export type IUpdate = Partial<ICreate>;
 
  /** Page of articles. */
  export interface IPage {
    /** List of articles. */
    articles: IBbsArticle[];
  }
}

Method type rules. Every method’s parameter type must be a keyworded object with static keys (no primitives, arrays, or unions). The return type must be an object or void. See typia.llm.application restrictions for the full list.

From an OpenAPI document

When the API you want to expose is described by Swagger/OpenAPI, use HttpLlm.controller — it produces controllers that registerMcpControllers accepts the same way:

src/main.ts


import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { registerMcpControllers } from "@typia/mcp";
import { HttpLlm } from "@typia/utils";
 
const server: McpServer = new McpServer({
  name: "my-server",
  version: "1.0.0",
});
 
registerMcpControllers({
  server,
  controllers: [
    HttpLlm.controller({
      name: "shopping",
      document: await fetch(
        "https://shopping-be.wrtn.ai/editor/swagger.json",
      ).then((r) => r.json()),
      connection: {
        host: "https://shopping-be.wrtn.ai",
        headers: { Authorization: "Bearer ********" },
      },
    }),
  ],
});

Every operation in the Swagger document becomes an MCP tool, with the same harness wrapping each one.

The function calling harness

Every tool registered through registerMcpControllers carries built-in lenient JSON parsing, type coercion, and validation feedback — same as the underlying typia.llm.application. When validation fails, the tool returns the input annotated with // ❌ markers, which the LLM reads and self-corrects from:


{
  "name": "John",
  "age": "twenty",      // ❌ [{"path":"$input.age","expected":"number"}]
  "email": "not-an-email", // ❌ [{"path":"$input.email","expected":"string & Format<\"email\">"}]
  "hobbies": "reading"  // ❌ [{"path":"$input.hobbies","expected":"Array<string>"}]
}

For the mechanics of parse / coerce / validate / stringify, see LlmJson. For the same harness pattern in typia.llm.application, see Function calling harness.

Preserve mode

By default registerMcpControllers owns the server’s tool list. If you’ve already registered tools the standard way with McpServer.registerTool(...) and want typia’s tools to coexist, pass preserve: true.

Preserve test

test_mcp_class_controller_preserve.ts


import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { TestValidator } from "@nestia/e2e";
import { ILlmController } from "@typia/interface";
import { registerMcpControllers } from "@typia/mcp";
import typia from "typia";
import { z } from "zod";
 
import { Calculator } from "../structures/Calculator";
 
export const test_mcp_class_controller_preserve = async (): Promise<void> => {
  // 1. Create class-based controller using typia.llm.controller
  const controller: ILlmController<Calculator> =
    typia.llm.controller<Calculator>("calculator", new Calculator());
 
  // 2. Create McpServer with tools capability
  const mcpServer: McpServer = new McpServer(
    {
      name: "test-server",
      version: "1.0.0",
    },
    {
      capabilities: {
        tools: {},
      },
    },
  );
 
  // 3. Register existing tool via McpServer.registerTool() with zod schema
  const inputSchema: z.ZodObject<{ message: z.ZodString }> = z.object({
    message: z.string().describe("Message to echo"),
  });
  (mcpServer.registerTool as Function)(
    "echo",
    {
      description: "Echo a message",
      inputSchema,
    },
    async (args: z.infer<typeof inputSchema>) => ({
      content: [
        {
          type: "text",
          text: args.message,
        },
      ],
    }),
  );
 
  // 4. Register with preserve: true
  registerMcpControllers({
    server: mcpServer,
    controllers: [controller],
    preserve: true,
  });
 
  // 5. Verify private API IS used
  const registeredTools: Record<string, unknown> =
    (mcpServer as any)._registeredTools ?? {};
  const handlersInitialized: boolean = (mcpServer as any)
    ._toolHandlersInitialized;
 
  TestValidator.equals(
    "existing echo tool should be present",
    Object.keys(registeredTools).includes("echo"),
    true,
  );
  TestValidator.equals(
    "_toolHandlersInitialized should be true",
    handlersInitialized,
    true,
  );
 
  // 6. Call tools/list to verify all tools (echo + calculator)
  const rawServer: Server = mcpServer.server;
  const requestHandlers: Map<string, Function> = (rawServer as any)
    ._requestHandlers;
  const listHandler: Function = requestHandlers.get("tools/list")!;
  const result: { tools: { name: string }[] } = await listHandler(
    {
      method: "tools/list",
      params: {},
    },
    {
      signal: new AbortController().signal,
    },
  );
 
  const toolNames: string[] = result.tools.map((t) => t.name).sort();
 
  // Should have 5 tools: echo + add, subtract, multiply, divide
  TestValidator.equals("should have 5 tools total", result.tools.length, 5);
  TestValidator.predicate(
    "should include echo tool",
    toolNames.includes("echo"),
  );
  TestValidator.predicate("should include add tool", toolNames.includes("add"));
  TestValidator.predicate(
    "should include subtract tool",
    toolNames.includes("subtract"),
  );
  TestValidator.predicate(
    "should include multiply tool",
    toolNames.includes("multiply"),
  );
  TestValidator.predicate(
    "should include divide tool",
    toolNames.includes("divide"),
  );
};

In the test above, an "echo" tool registered through McpServer.registerTool lives alongside four calculator tools registered through registerMcpControllers — five tools total. If two registrations would produce the same tool name, registration fails at startup so you can fix it before clients ever see the conflict.

Runtime errors

There are two distinct failure modes when a tool is called:

Validation error — the LLM passed arguments that don’t match the schema. The tool returns isError: true with the annotated input (same // ❌ markers as above) so the model can fix it.
Runtime error — the tool itself threw (e.g. divide-by-zero, network error, business-rule violation). The tool returns isError: true with the error name and message.

In both cases the MCP conversation stays alive — the model sees the failure and can either retry with different inputs or inform the user.

Error handling test

test_mcp_class_controller_error_handling.ts


import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
import { TestValidator } from "@nestia/e2e";
import { ILlmController } from "@typia/interface";
import { registerMcpControllers } from "@typia/mcp";
import typia from "typia";
 
import { Calculator } from "../structures/Calculator";
 
/**
 * Verifies MCP tool handler catches runtime errors and returns `isError: true`.
 *
 * Locks the error-catching branch of `McpControllerRegistrar.handleToolCall`.
 * When a tool's `execute` function throws (e.g. division by zero), the handler
 * must catch the error and return a well-formed `CallToolResult` with
 * `isError: true` and the error message as text content, rather than letting
 * the exception propagate and crash the MCP server.
 *
 * 1. Register a `Calculator` controller with the MCP server.
 * 2. Invoke the `divide` tool with `y: 0` to trigger a division-by-zero error.
 * 3. Assert the result has `isError: true`.
 * 4. Assert the text content contains the "Division by zero" error message.
 */
export const test_mcp_class_controller_error_handling =
  async (): Promise<void> => {
    // 1. Create class-based controller using typia.llm.controller
    const controller: ILlmController<Calculator> =
      typia.llm.controller<Calculator>("calculator", new Calculator());
 
    // 2. Create McpServer with tools capability
    const mcpServer: McpServer = new McpServer(
      {
        name: "test-server",
        version: "1.0.0",
      },
      {
        capabilities: {
          tools: {},
        },
      },
    );
 
    // 3. Register controller
    registerMcpControllers({
      server: mcpServer,
      controllers: [controller],
      preserve: false,
    });
 
    // 4. Get tools/call handler
    const rawServer: Server = mcpServer.server;
    const requestHandlers: Map<string, Function> = (rawServer as any)
      ._requestHandlers;
    const callHandler: Function = requestHandlers.get("tools/call")!;
 
    // 5. Test divide by zero (throws an error)
    const result: CallToolResult = await callHandler(
      {
        method: "tools/call",
        params: {
          name: "divide",
          arguments: {
            x: 10,
            y: 0,
          },
        },
      },
      { signal: new AbortController().signal },
    );
 
    // 6. Verify the result is an error
    TestValidator.predicate(
      "result should have isError: true",
      () => result.isError === true,
    );
 
    // 7. Verify the error message contains the expected text
    TestValidator.predicate(
      "error should contain division by zero message",
      () =>
        result.content.some(
          (c) =>
            c.type === "text" &&
            (c as { type: "text"; text: string }).text.includes(
              "Division by zero",
            ),
        ),
    );
  };

Where to go next

Same idea, different framework → Vercel AI SDK · LangChain
Source TypeScript class for the tools → typia.llm.application
Source OpenAPI document for the tools → HttpLlm
Harness internals (parse, coerce, validate, stringify) → LlmJson
Building a full chatbot → Agentica