xmcp

library0.6.7jsnpmunverified

xmcp is a TypeScript-first framework designed for building and deploying Model Context Protocol (MCP) servers. It aims to simplify the development experience for creating powerful tools within the MCP ecosystem, providing features like file system routing for automatic tool and prompt registration, hot reloading for rapid development, and a robust middleware system for authentication and custom logic. Currently at version 0.6.7, the project maintains an active development pace with frequent minor and patch releases (often weekly or bi-weekly), incorporating new features, security updates, and performance improvements. Key differentiators include its focus on developer experience, support for various deployment targets like Vercel and Cloudflare, and an 'elicit' mechanism within tool handlers for requesting structured user input.

llm-agents web-framework devops aws gcp

npm install xmcp

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · XMCP

xmcp

llm-agentsjavascriptv0.6.7

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

defineConfig

✓ import { defineConfig } from 'xmcp'

✗ const { defineConfig } = require('xmcp')

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

ToolHandlerContext

✓ import { type ToolHandlerContext } from 'xmcp'

✗ import { 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

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

✗ import { elicit } from 'xmcp'

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

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.

Debug

Known issues

breakingThe 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.

affects: >=0.6.0

breakingAs 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.

affects: >=0.6.1

gotchaxmcp 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.

affects: >=0.5.8

gotchaPrior 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.

affects: <0.6.7

breakingMultiple 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.

affects: <0.6.6

Errors

Common errors & fixes

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

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')

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.

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.

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.

Upgrade

Version history

0.6.7latest on npm

Audit

Dependencies

reactrequiredPeer dependency for UI-related components or adapters.

react-domrequiredPeer dependency for UI-related components or adapters.

zodrequiredPeer dependency for schema validation and type inference, commonly used for input/output schemas.

Agent activity

45 hits · last 30 days

node

Perplexity

OpenAI (training)

Resources

githubhttps://github.com/basementstudio/xmcp ↗

packagehttps://www.npmjs.com/package/xmcp ↗

homepagehttps://xmcp.dev ↗