Add support for logging capability

apps/website/content/docs/core-concepts/logging.mdx

@@ -0,0 +1,100 @@
+---
+title: "Logging"
+metadataTitle: "Logging | xmcp Documentation"
+publishedAt: "2026-03-17"
+summary: "Send structured log messages from your MCP server to connected clients."
+description: "The logging capability lets your tools, prompts, and resources send structured log messages to clients. Clients can control verbosity via log levels, and messages are automatically filtered based on the client's preference."
+---
+
+xmcp supports the MCP [logging capability](https://modelcontextprotocol.io/specification/draft/server/utilities/logging), which provides a standardized way for servers to send structured log messages to clients.
+
+## Usage
+
+Import `logger` from `xmcp` and call any log method directly in your handlers:
+
+```typescript title="src/tools/sync-data.ts"
+import { z } from "zod";
+import { type InferSchema, logger } from "xmcp";
+
+export const schema = {
+  source: z.string().describe("Data source to sync from"),
+};
+
+export const metadata = {
+  name: "sync-data",
+  description: "Sync data from an external source",
+};
+
+export default async function syncData({ source }: InferSchema<typeof schema>) {
+  logger.info(`Starting sync from ${source}`, "sync-data");
+
+  try {
+    const records = await fetchRecords(source);
+    logger.debug({ recordCount: records.length }, "sync-data");
+
+    await processRecords(records);
+    logger.info("Sync completed successfully", "sync-data");
+
+    return `Synced ${records.length} records`;
+  } catch (error) {
+    logger.error({ error: String(error), source }, "sync-data");
+    return { isError: true, content: [{ type: "text", text: "Sync failed" }] };
+  }
+}
+```
+
+No need to accept `extra` as a parameter, `logger` automatically resolves the current server session from async context.
+
+## Log Levels
+
+The logging levels follow [RFC 5424](https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1) severity levels, from least to most severe:
+
+| Method        | Description                      | Example Use Case           |
+| ------------- | -------------------------------- | -------------------------- |
+| `debug`       | Detailed debugging information   | Function entry/exit points |
+| `info`        | General informational messages   | Operation progress updates |
+| `notice`      | Normal but significant events    | Configuration changes      |
+| `warning`     | Warning conditions               | Deprecated feature usage   |
+| `error`       | Error conditions                 | Operation failures         |
+| `critical`    | Critical conditions              | System component failures  |
+| `alert`       | Action must be taken immediately | Data corruption detected   |
+| `emergency`   | System is unusable               | Complete system failure    |
+
+## Sending a Message
+
+Each log method has the same signature:
+
+```typescript
+logger.info(data: unknown, loggerName?: string): void
+```
+
+- **`data`**: The log payload. Can be a string, number, object, or any JSON-serializable value.
+- **`loggerName`** _(optional)_: A label to identify the source of the message (e.g., your tool name or a subsystem).
+
+## Client-Controlled Log Level
+
+Clients can send a `logging/setLevel` request to control which messages they receive. When a client sets the level to `"warning"`, only messages at `warning` severity and above are delivered; `debug`, `info`, and `notice` messages are silently dropped.
+
+If no level has been set by the client, all messages are sent.
+
+## Works Everywhere
+
+Logging is available in all handler types:
+
+```typescript title="src/prompts/analyze.ts"
+import { logger } from "xmcp";
+
+export default async function analyze(args: any) {
+  logger.info("Running analysis prompt", "analyze");
+  return "Analysis result...";
+}
+```
+
+```typescript title="src/resources/status.ts"
+import { logger } from "xmcp";
+
+export default async function status(args: any) {
+  logger.debug("Fetching system status", "status");
+  return "System OK";
+}
+```

apps/website/content/docs/core-concepts/meta.json

@@ -4,6 +4,7 @@
     "tools",
     "prompts",
     "resources",
+    "logging",
     "middlewares",
     "css",
     "external-clients"

examples/logging/.gitignore

@@ -0,0 +1,3 @@
+.vercel
+.xmcp
+xmcp-env.d.ts

examples/logging/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "Logging",
+  "description": "Learn how to send structured log messages to clients using the MCP logging capability",
+  "keywords": [
+    "logging"
+  ],
+  "scripts": {
+    "build": "xmcp build",
+    "dev": "xmcp dev",
+    "start": "node dist/http.js"
+  },
+  "dependencies": {
+    "xmcp": "workspace:*",
+    "zod": "^4.0.10"
+  }
+}

examples/logging/src/tools/process-data.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { type InferSchema, type ToolMetadata, logger } from "xmcp";
+
+export const schema = {
+  a: z.number().describe("First number"),
+  b: z.number().describe("Second number"),
+};
+
+export const metadata: ToolMetadata = {
+  name: "add",
+  description: "Add two numbers together",
+};
+
+export default async function add({ a, b }: InferSchema<typeof schema>) {
+  logger.info(`Adding ${a} + ${b}`, "add");
+
+  const result = a + b;
+
+  logger.debug({ a, b, result }, "add");
+
+  return `Result: ${result}`;
+}

examples/logging/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "es2017",
+    "module": "commonjs",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true
+  },
+  "include": ["xmcp-env.d.ts", "src/**/*.ts"]
+}

examples/logging/xmcp.config.ts

@@ -0,0 +1,14 @@
+import { XmcpConfig } from "xmcp";
+
+const config: XmcpConfig = {
+  http: true,
+  paths: {
+    prompts: false,
+    resources: false,
+  },
+  typescript: {
+    skipTypeCheck: true,
+  },
+};
+
+export default config;

packages/xmcp/src/index.ts

@@ -9,6 +9,8 @@ export type {
   ToolExtraArguments,
   InferSchema,
 } from "./types/tool";
+export type { Logger } from "./runtime/utils/logger";
+export { logger } from "./runtime/utils/logger";
 export type { PromptMetadata } from "./types/prompt";
 export type { ResourceMetadata } from "./types/resource";
 export type { UIMetadata } from "./types/ui-meta";

packages/xmcp/src/runtime/adapters/nextjs/handler/server-lifecycle.ts

@@ -43,7 +43,9 @@ export async function initializeMcpServer(): Promise<McpServer> {
 
   await Promise.all([...toolPromises, ...promptPromises, ...resourcePromises]);
 
-  const server = new McpServer(INJECTED_CONFIG);
+  const server = new McpServer(INJECTED_CONFIG, {
+    capabilities: { logging: {} },
+  });
 
   await configureServer(server, toolModules, promptModules, resourceModules);
 

packages/xmcp/src/runtime/transports/http/stateless-streamable-http.ts

@@ -27,6 +27,7 @@ import {
 } from "@/runtime/utils/request-tool-names";
 import { CorsConfig, corsConfigSchema } from "@/compiler/config/schemas";
 import { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types";
+import { setLogLevel, type LogLevel } from "@/runtime/utils/logger";
 
 // Global type declarations for tool name context
 declare global {
@@ -48,6 +49,7 @@ export class StatelessHttpServerTransport extends BaseHttpServerTransport {
     }
   > = new Map();
   private _requestToCollectorMapping: Map<string | number, string> = new Map();
+  private _bufferedNotifications: JsonRpcMessage[] = [];
 
   constructor(debug: boolean, bodySizeLimit: string) {
     super();
@@ -87,10 +89,8 @@ export class StatelessHttpServerTransport extends BaseHttpServerTransport {
     const requestId = message.id;
 
     if (requestId === undefined || requestId === null) {
-      // In stateless mode, we can't handle notifications without request IDs
-      if (this.debug) {
-        console.log("[StatelessHTTP] Dropping notification without request ID");
-      }
+      // Buffer notifications (e.g. logging) to include in the response
+      this._bufferedNotifications.push(message);
       return;
     }
 
@@ -109,10 +109,16 @@ export class StatelessHttpServerTransport extends BaseHttpServerTransport {
             "Content-Type": "application/json",
           };
 
+          const allMessages = [
+            ...this._bufferedNotifications,
+            ...collector.responses,
+          ];
+          this._bufferedNotifications = [];
+
           const responseBody =
-            collector.responses.length === 1
-              ? collector.responses[0]
-              : collector.responses;
+            allMessages.length === 1
+              ? allMessages[0]
+              : allMessages;
 
           collector.res
             .writeHead(200, headers)
@@ -207,6 +213,13 @@ export class StatelessHttpServerTransport extends BaseHttpServerTransport {
         ? rawMessage
         : [rawMessage];
 
+      // Capture logging/setLevel so the level persists across stateless requests
+      for (const msg of messages) {
+        if (msg.method === "logging/setLevel" && msg.params?.level) {
+          setLogLevel(msg.params.level as LogLevel);
+        }
+      }
+
       const hasRequests = messages.some(
         (msg) => msg.method && msg.id !== undefined
       );

packages/xmcp/src/runtime/transports/http/web-stateless-http.ts

@@ -1,6 +1,7 @@
 import { Transport } from "@modelcontextprotocol/sdk/shared/transport";
 import { MessageExtraInfo } from "@modelcontextprotocol/sdk/types";
 import { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types";
+import { setLogLevel, type LogLevel } from "@/runtime/utils/logger";
 
 export interface JsonRpcMessage {
   jsonrpc: string;
@@ -29,6 +30,7 @@ export class WebStatelessHttpTransport implements Transport {
     }
   > = new Map();
   private _requestToCollectorMapping: Map<string | number, string> = new Map();
+  private _bufferedNotifications: JsonRpcMessage[] = [];
 
   // MCP SDK transport interface
   onmessage?: (message: JsonRpcMessage, extra?: MessageExtraInfo) => void;
@@ -80,10 +82,8 @@ export class WebStatelessHttpTransport implements Transport {
     const requestId = message.id;
 
     if (requestId === undefined || requestId === null) {
-      // In stateless mode, we can't handle notifications without request IDs
-      if (this.debug) {
-        this.log("Dropping notification without request ID");
-      }
+      // Buffer notifications (e.g. logging) to include in the response
+      this._bufferedNotifications.push(message);
       return;
     }
 
@@ -99,10 +99,16 @@ export class WebStatelessHttpTransport implements Transport {
 
         // All responses collected, resolve the promise
         if (collector.requestIds.size === 0) {
+          const allMessages = [
+            ...this._bufferedNotifications,
+            ...collector.responses,
+          ];
+          this._bufferedNotifications = [];
+
           const responseBody =
-            collector.responses.length === 1
-              ? collector.responses[0]
-              : collector.responses;
+            allMessages.length === 1
+              ? allMessages[0]
+              : allMessages;
 
           collector.resolve(
             new Response(JSON.stringify(responseBody), {
@@ -201,6 +207,13 @@ export class WebStatelessHttpTransport implements Transport {
         ? rawMessage
         : [rawMessage];
 
+      // Capture logging/setLevel so the level persists across stateless requests
+      for (const msg of incomingMessages) {
+        if (msg.method === "logging/setLevel" && msg.params?.level) {
+          setLogLevel(msg.params.level as LogLevel);
+        }
+      }
+
       const invalidResponses: JsonRpcMessage[] = [];
       const messages = incomingMessages.filter((msg) => {
         if (msg?.jsonrpc === "2.0") {