Skip to content

Generate typed tools ​

Point a config file at your MCP server and let mcp-tool-codegen generate write the types, the tool map, a typed client and, if you want them, React hooks.

Requirements: an MCP server that answers over streamable HTTP, Node.js 22.18 or later.

The examples on this page use the server of examples/tasks, started as in Getting started. Paths in the output are those of a project in /home/you/tasks-client, and a line ... marks output left out.

1. Install the generator ​

The generator is a dev dependency. The code it writes imports the core package at run time:

sh
pnpm add -D @miragon/mcp-toolkit-tool-codegen@4
pnpm add @miragon/mcp-toolkit-tool-codegen-core@4

Keep the generator and its runtime packages on the same minor version. The generator writes code against the runtime API of its own release and declares the runtime packages as optional peers (~ its version), so your package manager reports a mismatch. The @4 in each command pins the major: a package manager that holds back fresh releases (a minimum release age) could otherwise install the previous major of one package next to the current major of another.

2. Look at what the server lists ​

inspect prints the server's tools as a Markdown table, with the hook kind each tool would get:

sh
pnpm exec mcp-tool-codegen inspect --url http://localhost:4000/mcp
txt
| name | hook | description | input |
| --- | --- | --- | --- |
| list-tasks | query | Lists the tasks in the order they were added. | done |
| get-task | query | Returns one task. | id |
| add-task | mutation | Adds an open task and returns it. | title |
| complete-task | mutation | Marks a task as done and returns it. Completing a done task changes nothing. | id |

A tool gets a query hook only when the server annotates it readOnlyHint: true. MCP reads a missing hint as false, and a query runs its tool again on every refetch, so an unannotated write never becomes a query. For a server that needs a token, pass --token <token>, or --header <name> --header-value <value> for a header of its own.

3. Write the config ​

Create codegen.config.ts next to your package.json, the file the CLI reads by default:

ts
import type { CodegenConfig } from "@miragon/mcp-toolkit-tool-codegen"

const config: CodegenConfig = {
  name: "tasks",
  url: process.env.TASKS_MCP_URL ?? "http://localhost:4000/mcp",
  out: "./src/generated",
}

export default config
  • name names the generated code: TasksToolMap, createTasksClient and the hooks useTasks<Tool>Query and useTasks<Tool>Mutation. It starts with a letter, followed by letters, digits, - and _.
  • url is the server's streamable HTTP endpoint, http: or https:, without credentials. Read from an environment variable, as here, it lets CI point the same config at another host.
  • out is the output directory, resolved against the config file's directory.

Node.js loads the config with its own type stripping, so only erasable TypeScript works in it: type imports and annotations, no enums or namespaces. Configuration lists every field.

4. Generate ​

generate fetches the server's tools/list and writes the files into out:

sh
pnpm exec mcp-tool-codegen generate
txt
generated 4 tools: tools.ts in /home/you/tasks-client/src/generated

tools.ts holds an input and an output type for each tool, the tool map TasksToolMap keyed by the server's own tool names, TasksToolName, TasksCallTool, createTasksClient and TasksClient. It imports only @miragon/mcp-toolkit-tool-codegen-core. Its first three lines mark it as generated and name the server by its origin only, without path, query or credentials:

ts
// AUTO-GENERATED by @miragon/mcp-toolkit-tool-codegen. Do not edit by hand.
// Regenerate with: mcp-tool-codegen generate
// Source: http://localhost:4000

Commit the generated files, so a change to the server's tools shows up as a diff in review. The tools are sorted by name, the files regenerate byte for byte on the same lockfile and come out formatted as Prettier prints them (print width 100, double quotes, no semicolons, trailing commas); exclude out from your formatter if your style differs.

A tool without an outputSchema gets the output type unknown. Give the tool an output schema on the server, or set its type with an override. Every export is listed in Generated code.

A server that lists no tools fails the run, and the files in out stay as they are:

txt
mcp-tool-codegen: the server at http://localhost:4000 lists no tools, so nothing was generated. Check that "url" names its MCP endpoint, path included, that the server registers its tools, and that "auth" or "headers" carry the token or scope it needs to list them.

Run inspect with the same URL and token to see what the server lists for them.

Add React hooks ​

Install the React package and TanStack Query, and set react: true in the config:

sh
pnpm add @miragon/mcp-toolkit-tool-codegen-react@4 @tanstack/react-query react
ts
const config: CodegenConfig = {
  name: "tasks",
  url: process.env.TASKS_MCP_URL ?? "http://localhost:4000/mcp",
  out: "./src/generated",
  react: true,
}

generate now also writes hooks.tsx:

sh
pnpm exec mcp-tool-codegen generate
txt
generated 4 tools: tools.ts, hooks.tsx in /home/you/tasks-client/src/generated

hooks.tsx exports useTasksListTasksQuery and useTasksGetTaskQuery for the read-only tools, useTasksAddTaskMutation and useTasksCompleteTaskMutation for the others, and the query key tasksQueryKey. When you turn react off again, generate removes the hooks.tsx it wrote:

txt
generated 4 tools: tools.ts in /home/you/tasks-client/src/generated
removed the stale hooks.tsx (react is off)

Use the React hooks shows how to wire them into an app.

Override a tool ​

overrides changes the generated code for single tools. It is keyed by the tool name as the server lists it, and each entry takes:

  • identifier: the name to build the tool's identifiers from, a letter followed by letters and digits. For a tool whose name collides with another's, is reserved or has no ASCII letter or digit.
  • input, output: a TypeScript type expression that replaces the generated type, for a tool without an outputSchema or with a schema the generator cannot read.
  • hook: "query" or "mutation", instead of the readOnlyHint rule.

Here get-task becomes readTask in the generated code:

ts
const config: CodegenConfig = {
  name: "tasks",
  url: process.env.TASKS_MCP_URL ?? "http://localhost:4000/mcp",
  out: "./src/generated",
  react: true,
  overrides: {
    "get-task": { identifier: "readTask" },
  },
}

The tool map keeps the server's name, while the types, the client method and the hook take the new one:

ts
// tools.ts
"get-task": {
  input: TasksReadTaskInput
  output: TasksReadTaskOutput
}
// ...
readTask: (args: TasksReadTaskInput, options?: ToolCallOptions) =>
  call("get-task", args, options),

// hooks.tsx
export function useTasksReadTaskQuery<TSelected = TasksReadTaskOutput>(

An override for a tool the server does not list fails the run. A 2.x override key with the prefixed name, such as "tasks_get-task", is the common case:

txt
mcp-tool-codegen: "overrides" names tools the server does not list: "tasks_get-task"

An output override changes the type, not what arrives at run time. The core package reads a result without structuredContent from its first text block, as JSON when it parses as JSON, so text such as "2.10" arrives as a number: output: "string" is right only for text that never parses as JSON.

Send a token or headers at build time ​

generate connects to the server at build time, and auth and headers go with that connection. Read secrets from the environment, never from the committed config:

ts
import type { CodegenConfig } from "@miragon/mcp-toolkit-tool-codegen"

const token = process.env.TASKS_TOKEN

const config: CodegenConfig = {
  name: "tasks",
  url: "https://tasks.example.com/mcp",
  auth: token ? { mode: "bearer", token } : { mode: "none" },
  headers: { "X-Tenant": "acme" },
  out: "./src/generated",
}

export default config
  • auth is { mode: "none" } (the default), { mode: "bearer", token } for Authorization: Bearer <token>, or { mode: "header", headerName, value } for a header of your own.
  • The generator runs no OAuth flow: run it once yourself and pass the access token as bearer.
  • headers are extra request headers. Names compare case-insensitively, and a header named like the auth header replaces it.
  • Header and auth values must not contain line breaks, control characters or characters beyond Latin-1. The error names the header, never the value.

Credentials in the URL fail the run without printing it:

txt
mcp-tool-codegen: invalid codegen config:
  | - "url" must not carry credentials: put them into "auth"

Load the config on older Node.js or in CommonJS ​

The config is an ES module that Node.js loads itself. Two setups need another file:

  • Node.js older than 22.18, below the CLI's engines range (npm and pnpm only warn about it), cannot load a .ts config. Update Node.js, use a .mjs config, or run the CLI through tsx (a dev dependency then): NODE_OPTIONS="--import tsx" pnpm exec mcp-tool-codegen generate. Otherwise the run fails with:

    txt
    mcp-tool-codegen: cannot load /home/you/tasks-client/codegen.config.ts (Node.js loads a .ts config from version 22.18 on; use a .mjs config, or run the CLI with NODE_OPTIONS="--import tsx"): Unknown file extension ".ts" for /home/you/tasks-client/codegen.config.ts
  • A package with "type": "commonjs" makes Node.js read .ts and .js as CommonJS, where export default is a syntax error. Name the file codegen.config.mts (or .mjs) and pass it: pnpm exec mcp-tool-codegen generate --config codegen.config.mts. With the default name, the run fails after a warning from Node.js:

    txt
    ...
    mcp-tool-codegen: cannot load /home/you/tasks-client/codegen.config.ts (in a CommonJS package, name the config codegen.config.mts and pass it with --config): Unexpected token 'export'

out always resolves against the directory of the config file you pass.

Next steps ​