createMcpServer
Create a raw MCP server from a Kizuna API for use with any transport (stdio, SSE, etc.).
MCP support is new and still settling. createMcpServer and the generated tool surface may change while v2 is in beta, so pin your version if you depend on them.
Create a raw MCP server from a Kizuna API. Use this when you want full control over the transport, for example stdio for CLI tools or SSE for custom setups.
To serve it from your app, install mcpPlugin instead.
pnpm add @kizunajs/mcp@betabun add @kizunajs/mcp@betanpm install @kizunajs/mcp@betaimport { createMcpServer } from '@kizunajs/mcp';Parameters
createMcpServer(api: ApiWithRouter, options?: McpServerOptions): McpServer| Parameter | Type | Required | Description |
|---|---|---|---|
api | ApiWithRouter | Yes | The api from defineConfig |
options | McpServerOptions | No | Configuration options |
Options
| Option | Default | Description |
|---|---|---|
name | 'MCP Server' | Human-readable name shown to AI assistants |
version | '1.0.0' | Semantic version string |
onlyReadOnly | false | Keep only the methods RFC 9110 calls safe, so nothing an assistant calls can change data |
instructions | built from your tags | Appended to the generated overview |
handlerContext | none | Extra context spread into every handler call |
credentialHeaders | none | Headers of the MCP transport request, used to run guards on secured tools |
transportAuth | none | A scheme the transport already verified: its guard is skipped, and context reaches handlers under auth.<scheme> |
Which routes it publishes is each route's own business: the ones declaring tool, less the ones whose shape a tool call cannot carry. A route whose contentType is multipart/form-data or application/x-www-form-urlencoded never publishes, because tool input is JSON, and neither does one whose response streams, because a tool result is one value.
Secured routes
Each call to a secured tool runs the same guard pipeline as an HTTP request, extracting the credential from credentialHeaders.
Driving the transport yourself means passing those headers along. For stdio there is no HTTP request, so supply whatever the environment provides:
const server = createMcpServer(kizuna.api, {
name: 'My API',
credentialHeaders: {
authorization: `Bearer ${process.env.API_TOKEN}`,
},
});Returns
An McpServer instance from @modelcontextprotocol/sdk. Connect it to any transport.
Example
import { createMcpServer } from '@kizunajs/mcp';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import kizuna from '../kizuna.config';
const server = createMcpServer(kizuna.api, {
name: 'My API',
version: '1.0.0',
});
await server.connect(new StdioServerTransport());See the MCP guide for connecting clients and tool input/output structure.