Server Concepts

Decorators describe the server: @McpApp sets server-wide settings, @Module groups features, @Injectable marks services, and @Tool, @Resource, and @Prompt mark what clients can call. The entry point in src/index.ts creates the application and starts it.

import 'reflect-metadata'; // Must be first
import { McpApplicationFactory } from '@nitrostack/core';
import { AppModule } from './app.module.js';

const server = await McpApplicationFactory.create(AppModule);
await server.start();

The pages that follow cover each part in depth: Bootstrap, Modules, the Server Lifecycle, and the Execution Context.

A Python server is modules, dependency injection, and a factory that bootstraps them. @module groups features, @injectable marks services, and @tool, @resource, and @prompt mark what clients can call. main.py creates the application from your root module and starts it.

import asyncio
from nitrostack import McpApplicationFactory
from app_module import AppModule

async def main():
    app = await McpApplicationFactory.create(AppModule)
    await app.start()

if __name__ == "__main__":
    asyncio.run(main())

You can also put the root module and the server's name and version on one class with @mcp_app:

from nitrostack import mcp_app, ServerConfig

@mcp_app(module=AppModule, server=ServerConfig(name="math-server", version="1.0.0"))
class App:
    pass

app = await McpApplicationFactory.create(App)

The factory initializes logging, the DIContainer, the imported modules, and your tools, resources, and prompts, then starts the transport.

@module(...) takes name, controllers, providers, imports, and exports. Controllers are the classes that hold @tool, @resource, and @prompt methods, providers are injectable services, imports are other modules such as ConfigModule or OAuthModule, and exports are the providers other modules may inject.

from nitrostack import module, ConfigModule
from modules.calculator.calculator_module import CalculatorModule
from health.system_health import SystemHealthCheck

@module(
    name="app",
    imports=[
        ConfigModule.for_root(env_file_path=".env", defaults={"PORT": "3000"}),
        CalculatorModule,
    ],
    providers=[SystemHealthCheck],
)
class AppModule:
    pass

Every handler receives an ExecutionContext with the request ID, a logger, metadata, and the authenticated user. See Execution Context for what it carries, and Execution Context in the Python reference for its fields.