Packages

@xtaskjs/mcp

Decorator-based MCP server builder, lifecycle hooks, and SDK transport adapters.

npm install @xtaskjs/mcp reflect-metadata @modelcontextprotocol/sdk Package path: packages/mcp

Overview

What this package owns in the runtime

MCP adds a decorator-driven server builder for Model Context Protocol servers. It registers tools, prompts, resources, and lifecycle hooks inside the xtaskjs runtime, and it can bridge the official @modelcontextprotocol/sdk transports for stdio or Streamable HTTP.

What it provides

McpServer(), McpTool(), McpPrompt(), and McpResource() declare server capabilities with DI-friendly classes.
OnMcpServerStart() and OnMcpServerStop() hook server lifecycle into application startup and shutdown.
InjectMcpService() and InjectMcpLifecycleManager() expose the runtime through DI-managed services.
createMcpSdkServerAdapter(), connectMcpSdkStdio(), and bindMcpSdkStreamableHttp() integrate with official MCP SDK transports.

How it fits

Pairs with @xtaskjs/core so the MCP runtime initializes and shuts down alongside the rest of the application.
Useful when an app needs to expose tools, prompts, resources, or authenticated endpoints over /mcp.
Demonstrated by the 28-mcp_server_app and 29-mcp_auth_http_app samples.

Usage Chart

How strongly this package shapes the runtime

Bootstrap

4/5

Dependency Injection

5/5

Tools / Prompts

5/5

Lifecycle Hooks

5/5

SDK Transport

4/5

Package Flow

How this package moves through xtaskjs runtime phases

Before startup

Import reflect-metadata, declare your MCP server class, and define tools, prompts, resources, or lifecycle hooks before application bootstrap.

During CreateApplication()

MCP integration registers the server with the xtaskjs container so the runtime can expose methods and lifecycle hooks when the application starts.

During transport binding

Use the official SDK adapters to connect stdio or Streamable HTTP transports, or protect the HTTP endpoint with security middleware.

API Surface

Representative exports from the upstream package

Server decorators

McpServer
McpTool
McpPrompt
McpResource

Lifecycle and runtime

McpService
InjectMcpService
InjectMcpLifecycleManager
OnMcpServerStart
OnMcpServerStop
getMcpServiceToken
getMcpLifecycleToken

Lifecycle and SDK adapters

initializeMcpIntegration
shutdownMcpIntegration
resetMcpIntegration
createMcpSdkServerAdapter
connectMcpSdkStdio
bindMcpSdkStreamableHttp

Usage

Typical adoption flow

1. Declare servers and handlers

Use McpServer, McpTool, McpPrompt, and McpResource on DI-managed classes to expose protocol capabilities.

2. Hook startup and shutdown

Apply OnMcpServerStart and OnMcpServerStop for initialization work, health checks, or graceful teardown.

3. Bind a transport

Connect the server through stdio or Streamable HTTP with the official MCP SDK helpers when you are ready to expose it externally.

Example

Reference snippet

Declare an MCP server with tools and hooks

import { Service } from "@xtaskjs/core";
import { McpPrompt, McpServer, McpTool, OnMcpServerStart, OnMcpServerStop } from "@xtaskjs/mcp";

@Service()
@McpServer({
  name: "docs-mcp",
  version: "1.0.0",
  instructions: "Expose documentation helpers over MCP",
  group: ["docs", "mcp"],
})
export class DocsMcpServer {
  @OnMcpServerStart()
  onStart() {}

  @OnMcpServerStop()
  onStop() {}

  @McpTool("search-docs", { description: "Search docs" })
  searchDocs(payload: { query: string }) {
    return { query: payload.query };
  }

  @McpPrompt("welcome", { description: "Generate a docs welcome prompt" })
  welcome(input?: { name?: string }) {
    return `Welcome ${input?.name || "world"}`;
  }
}

Samples

Official samples to inspect next

Reference samples: 28-mcp_server_app and 29-mcp_auth_http_app