xmcp: Model Context Protocol Framework

Common errors

• Error: Cannot find module 'react' or 'zod'

  cause A peer dependency (e.g., React or Zod) is missing or has a version incompatible with xmcp's requirements.
  fix Install the required peer dependencies with `npm install react react-dom zod` and ensure their versions satisfy xmcp's peer dependency ranges (e.g., `react@'>=19.0.0'`, `zod@'^3.25.76 || ^4.0.0'`).

• TypeError: Cannot read properties of undefined (reading 'elicit')

  cause The `extra` object, which contains the `elicit` function, was not correctly destructured or provided to the tool handler, or the handler signature is incorrect.
  fix Ensure your tool handler function is defined as `export default async function (_args, extra: ToolHandlerContext) { ... }` and that `extra` is correctly named and typed.

• Error: Tool file 'src/tools/my-tool.ts' must have a default export.

  cause xmcp's file system routing requires each tool file to have a default export, which is treated as the tool handler function.
  fix Add `export default async function (...) { ... }` to your tool file, ensuring it exports a valid asynchronous function.

• Deployment cancelled or not confirmed.

  cause The `elicit` function was invoked, but the user either explicitly declined the prompt (`result.action !== 'accept'`) or did not provide the necessary confirmations based on the `requestedSchema`.
  fix This is expected behavior. When using `extra.elicit()`, always check `result.action` and `result.content` to handle user cancellations or incomplete input gracefully. Provide clear feedback to the user on why an action was not taken.

Warnings

• breaking The experimental OAuth configuration and proxy were removed in version 0.6.0. Projects relying on these features will require refactoring to use alternative authentication plugins (e.g., Auth0, WorkOS, Clerk) or custom middleware.
  Fix: Migrate to supported authentication plugins like `@xmcp-dev/auth0`, `@xmcp-dev/workos`, or `@xmcp-dev/clerk`, or implement custom authentication middleware.
• breaking As of v0.6.0, the `resource` parameter for the OAuth authorization server changed from `baseurl` to `audience`. This change affects how OAuth clients should be configured.
  Fix: Update your OAuth client configurations to use `audience` instead of `baseurl` when interacting with the xmcp OAuth authorization server.
• gotcha xmcp relies on peer dependencies `react`, `react-dom` (both `>=19.0.0`), and `zod` (`^3.25.76 || ^4.0.0`). Mismatched versions can lead to runtime errors or unexpected behavior.
  Fix: Ensure your project's `package.json` explicitly lists and installs compatible versions of `react`, `react-dom`, and `zod` that satisfy xmcp's peer dependency requirements.
• gotcha Prior to v0.6.7, error handling for empty or malformed tool files was less robust, potentially leading to crashes or silent failures during server startup or tool invocation.
  Fix: Upgrade to xmcp v0.6.7 or newer to benefit from improved error handling. Ensure all tool files (`src/tools/*`) are valid TypeScript/JavaScript modules with a default export.
• breaking Multiple security updates were released across versions 0.6.2 and 0.6.5. Running older versions exposes projects to known vulnerabilities.
  Fix: It is strongly recommended to update to the latest stable version of xmcp immediately to incorporate all critical security patches.

Install

• npm install xmcp npm
• yarn add xmcp yarn
• pnpm add xmcp pnpm

Imports

• defineConfig
  wrong:

  const { defineConfig } = require('xmcp')

  correct:

  import { defineConfig } from 'xmcp'

  Used for defining the main xmcp server configuration. Primarily an ESM package, CommonJS `require` is not supported for core modules.
• ToolHandlerContext
  wrong:

  import { ToolHandlerContext } from 'xmcp'

  correct:

  import { type ToolHandlerContext } from 'xmcp'

  This is a TypeScript type representing the context object ('extra' in tool handlers) that provides utilities like `elicit`. Use `import type` for type-only imports to prevent bundling issues.
• elicit
  wrong:

  import { elicit } from 'xmcp'

  correct:

  const result = await extra.elicit({...});

  `elicit` is a method available on the `extra` (ToolHandlerContext) object passed to tool handler functions, not a direct export from the `xmcp` package.

Quickstart

Initializes an xmcp project and demonstrates defining a tool that uses the `extra.elicit` function to prompt the user for structured input before proceeding with a simulated deployment.

// First, initialize a new xmcp project:
// npx create-xmcp-app@latest my-xmcp-app
// cd my-xmcp-app

// Then, create a tool file within your project, for example, at src/tools/deploy.ts.
// xmcp automatically registers tools based on file system routing.

import { type ToolHandlerContext } from 'xmcp';

export default async function (
  _args: Record<string, any>, // Arguments received by the tool
  extra: ToolHandlerContext  // Context object providing utilities
) {
  console.log("Deployment tool invoked. Awaiting user input...");

  const result = await extra.elicit({
    message: "Please choose deployment parameters:",
    requestedSchema: {
      type: "object",
      properties: {
        environment: {
          type: "string",
          title: "Deployment Environment",
          enum: ["staging", "production"],
          description: "Target environment for deployment."
        },
        confirmAction: {
          type: "boolean",
          title: "Confirm Deployment",
          description: "Are you sure you want to proceed with deployment?",
          default: false
        }
      },
      required: ["environment", "confirmAction"],
    },
  });

  if (result.action !== "accept" || !result.content || !result.content.confirmAction) {
    return "Deployment action cancelled or not confirmed by the user.";
  }

  const { environment } = result.content;
  console.log(`Initiating deployment to ${environment}...`);
  // In a real application, replace this with actual deployment logic
  await new Promise(resolve => setTimeout(resolve, 3000)); // Simulate work

  return `Deployment to ${environment} completed successfully!`;
}

// To run this tool, start your xmcp development server (e.g., `npm run dev`).
// Then, interact with your MCP server via a compatible client or interface
// to invoke the 'deploy' tool, which will trigger the elicitation flow.