Typia Guide Documents

`registerMcpControllers()` function

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

MCP (Model Context Protocol) integration for typia.

registerMcpControllers() converts TypeScript classes or OpenAPI documents into MCP tools at once.

Every class method becomes a tool, JSDoc comments become tool descriptions, and TypeScript types become JSON schemas — all at compile time. For OpenAPI documents, every API endpoint is converted to an MCP tool with schemas from the specification.

Lenient JSON parsing, type coercion, and validation feedback are all embedded automatically — the complete function calling harness that turns unreliable LLM output into 100% correct structured data.

Setup

Terminal


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

From TypeScript Class

MCP Server

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(),
    ),
  ],
});

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[];
  }
}

Create controllers from TypeScript classes with typia.llm.controller<Class>(), and pass them to registerMcpControllers().

server: Target MCP server instance (McpServer or raw Server from @modelcontextprotocol/sdk)
controllers: Array of controllers created via typia.llm.controller<Class>() or HttpLlm.controller()
preserve: When true, typia tools coexist with existing McpServer.registerTool() tools. Default is false

Type Restrictions

Every method’s parameter type must be a keyworded object type with static keys — not a primitive, array, or union. The return type must also be an object type or void. Primitive return types like number or string are not allowed; wrap them in an object (e.g., { value: number }). See typia.llm.application() Restrictions for details.

From OpenAPI Document

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 ********" },
      },
    }),
  ],
});

Create controllers from OpenAPI documents with HttpLlm.controller(), and pass them to registerMcpControllers().

name: Controller name used as prefix for tool names
document: Swagger/OpenAPI document (v2.0, v3.0, or v3.1)
connection: HTTP connection info including host and optional headers

The Function Calling Harness

registerMcpControllers() embeds lenient JSON parsing, type coercion, and validation feedback in every tool — all automatically. When validation fails, the error is returned as text content with inline // ❌ comments at each invalid property:


{
  "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>"}]
}

The LLM reads this feedback and self-corrects on the next turn.

In the AutoBe project (AI-powered backend code generator by Wrtn Technologies ), qwen3-coder-next showed only 6.75% raw function calling success rate on compiler AST types. However, with the complete harness, it reached 100% — across all four tested Qwen models.

Working on compiler AST means working on any type and any use case.

AutoBeTest.IExpression


// Compiler AST may be the hardest type structure possible
//
// Unlimited union types + unlimited depth + recursive references
export type IExpression =
  | IBooleanLiteral
  | INumericLiteral
  | IStringLiteral
  | IArrayLiteralExpression   // <- recursive (contains IExpression[])
  | IObjectLiteralExpression  // <- recursive (contains IExpression)
  | INullLiteral
  | IUndefinedKeyword
  | IIdentifier
  | IPropertyAccessExpression // <- recursive
  | IElementAccessExpression  // <- recursive
  | ITypeOfExpression         // <- recursive
  | IPrefixUnaryExpression    // <- recursive
  | IPostfixUnaryExpression   // <- recursive
  | IBinaryExpression         // <- recursive (left & right)
  | IArrowFunction            // <- recursive (body is IExpression)
  | ICallExpression           // <- recursive (args are IExpression[])
  | INewExpression            // <- recursive
  | IConditionalPredicate     // <- recursive (then & else branches)
  | ... // 30+ expression types total

Preserve Mode

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"),
  );
};

By default, registerMcpControllers() replaces the MCP server’s tool handlers (standalone mode). Set preserve: true to coexist with McpServer.registerTool().

In the above test, the "echo" tool registered via McpServer.registerTool() and the calculator tools registered via registerMcpControllers() work together — 5 tools total. If duplicate names are detected, it throws at registration time.

registerMcpControllers() function

undefined

undefined

undefined

undefined

Setup

From TypeScript Class

MCP Server

undefined

undefined

undefined

From OpenAPI Document

The Function Calling Harness

Preserve Mode

Preserve Test

undefined

`registerMcpControllers()` function