Add type safety with TypeScript

Type Safety

The Nuxt MCP module provides full TypeScript support with complete type inference and type safety.

Auto-Imports

All helper functions and types are auto-imported in your server files:

Functions:

• defineMcpTool, defineMcpResource, defineMcpPrompt, defineMcpHandler, defineMcpApp
• imageResult, audioResult (binary media helpers for tool responses)
• completable, extractToolNames
• useMcpSession, useMcpServer, useMcpLogger, useMcpElicitation, useMcpApp
• listMcpTools, listMcpResources, listMcpPrompts, listMcpDefinitions
• getMcpTools, getMcpResources, getMcpPrompts

Types:

• McpRequestExtra — extra arguments passed to every tool, prompt, and resource handler (abort signal, auth info, session ID, metadata). Equivalent to RequestHandlerExtra<ServerRequest, ServerNotification> from the SDK.
• McpServerHelper — return type of useMcpServer().
• McpSessionStore — typed store returned by useMcpSession().
• McpClientNotifier, McpLogger, McpRequestLogger, McpUserFields, McpSessionFields — types behind useMcpLogger().
• McpElicitation, ElicitationFormParams, ElicitationFormResult, ElicitationUrlParams, ElicitationUrlResult, ElicitationMode — types behind useMcpElicitation().
• Common SDK protocol types are re-exported from a single import path: Annotations, CallToolResult, GetPromptResult, ReadResourceResult, Resource, ServerNotification, ServerRequest, ToolAnnotations.

import { z } from 'zod'

export default defineMcpTool({
  name: 'example',
  inputSchema: {
    message: z.string(),
  },
  handler: async ({ message }, extra: McpRequestExtra) => {
    // message is typed as string
    // extra.signal, extra.authInfo, extra.sessionId are available
  },
})

You can disable auto-imports entirely with autoImports: false in your configuration and import explicitly from @nuxtjs/mcp-toolkit/server instead.

Type Inference

Tool Input Types

Input types are automatically inferred from your inputSchema:

import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  name: 'example',
  inputSchema: {
    name: z.string(),
    age: z.number(),
    email: z.string().email().optional(),
  },
  handler: async ({ name, age, email }) => {
    // name: string
    // age: number
    // email: string | undefined
  },
})

Tool Output Types

Output types are inferred from outputSchema:

import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  name: 'example',
  inputSchema: {
    value: z.number(),
  },
  outputSchema: {
    result: z.number(),
    doubled: z.number(),
  },
  handler: async ({ value }) => {
    const result = value * 2

    return {
      structuredContent: {
        result,      // TypeScript knows this is number
        doubled: result * 2, // TypeScript knows this is number
      },
    }
  },
})

Prompt Argument Types

Prompt argument types are inferred from inputSchema:

import { defineMcpPrompt } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpPrompt({
  name: 'example',
  inputSchema: {
    text: z.string(),
    maxLength: z.string().optional(),
  },
  handler: async ({ text, maxLength }) => {
    // text: string
    // maxLength: string | undefined
  },
})

Runtime Config Types

Access typed runtime configuration:

export default defineEventHandler((event) => {
  const config = useRuntimeConfig(event).mcp

  // config is typed with:
  // - enabled: boolean
  // - route: string
  // - browserRedirect: string
  // - name: string
  // - version: string
  // - dir: string

  return config
})

Next Steps

• Tools - Learn about creating tools
• Resources - Learn about creating resources
• Prompts - Learn about creating prompts