Plugin

The package exposes two Elysia plugins. Use mcp() for the normal application setup. Use withMcpMethods() only when a feature plugin must register standalone primitives before the application mounts the MCP endpoint.

mcpCopy Anchor Link

function mcp(options?: McpPluginOptions): Elysia

import { mcp } from '@mwillbanks/elysia-mcp-adapter'
import { Elysia } from 'elysia'

const app = new Elysia().use(
  mcp({
    server: {
      name: 'billing-api',
      version: '1.0.0'
    },
    path: '/mcp',
    allowedRoutes: '*'
  })
)

mcp() installs .mcpTool(), .mcpResource(), .mcpPrompt(), .mcpSkill(), .mcpInterceptor(), and .mcpEvent(), discovers eligible routes, and mounts the JSON-RPC transport.

The additive extension registration methods use these signatures:

mcpSkill(uri: string, skill: McpSkillBytes, options?: McpSkillRegistrationOptions): Elysia
mcpInterceptor(definition: McpInterceptorDefinition, handler: McpInterceptorHandler): Elysia
mcpEvent(definition: McpEventDefinition, handler: McpEventHandler): Elysia

Skill handlers serve registered bytes or delegate to McpSkillProvider. Interceptor handlers receive McpInterceptorInvocation and an invocation context with an abort signal. Event handlers receive McpEventPollRequest and return McpEventPollResult; larger registries can use McpEventProvider. See the extension API reference for provider, context, and result contracts.

Server metadataCopy Anchor Link

Response marshalingCopy Anchor Link

Modern coreCopy Anchor Link

Route handlers can read the current MCP call without accepting model-controlled headers:

import { getMcpInvocationContext } from '@mwillbanks/elysia-mcp-adapter'

new Elysia().post('/report', ({ request }) => {
  const invocation = getMcpInvocationContext(request)
  invocation?.reportProgress?.({ progress: 1, total: 1, message: 'complete' })
  return { inputResponses: invocation?.inputResponses }
})

getMcpInvocationContext() returns data only for the internal request that the adapter passes to app.handle(). The adapter removes the association after the route finishes.

Tool annotationsCopy Anchor Link

Annotations tell MCP clients about behavioral properties. They do not replace application authorization.

Shared metadata and iconsCopy Anchor Link

withMcpMethodsCopy Anchor Link

function withMcpMethods(): Elysia

new Elysia()
  .use(withMcpMethods())
  .mcpTool('health.read', () => ({ ok: true }))
  .use(mcp())

The plugin augments the Elysia instance without mounting /mcp. A later mcp() call reuses those explicit registrations and adds the endpoint.

Naming helpersCopy Anchor Link

The package also exports:

function sanitizeMcpName(value: string): string
function defaultOperationNameResolver(operation: McpRouteOperation): string

sanitizeMcpName() converts an arbitrary name into the MCP-compatible form. defaultOperationNameResolver() prefers detail.operationId, then derives a stable name from the HTTP method and path.

See Configuration for production defaults and Route-backed Tools for the per-route contract.