xmcp Framework Documentation

The xmcp framework provides several core features for building Model Context Protocol (MCP) servers:

• File System Routing: Tools and prompts are automatically registered based on files located in tools and prompts directories.
• Hot Reloading: Provides instant feedback during development.
• Middlewares: A toolkit for implementing authentication and custom logic.
• Extensible Configuration: Allows for customizable server configuration.
• Deploy Anywhere: Supports flexible deployment, including zero-configuration deployment on Vercel.

xmcp uses a declarative, file-system based architecture. By default, the framework uses auto-discovery to find and register tools, prompts, and resources based on their location within the src/ directory.

Default Directory Layout

• src/tools/: Files in this directory are automatically discovered as Tools.
• src/prompts/: Files in this directory are automatically discovered as Prompts.
• src/resources/: Files in this directory are automatically discovered as Resources.
• src/middleware.ts: An optional file used to process HTTP requests and responses.

If you need to change these default locations, you can configure custom directory paths in your xmcp.config.ts file.

To run xmcp, ensure your system meets these requirements:

• Node.js: version 20 or later.
• Operating Systems: macOS, Windows, or Linux.

An MCP Server Card is a JSON file published at /.well-known/mcp/server-card.json that allows agent discovery tools to automatically find and configure connections to your server.

In xmcp, the card is automatically generated based on the template fields defined in your xmcp.config.ts file. Specifically, it uses the name, description, and icons properties.

import type { XmcpConfig } from "xmcp";

const config: XmcpConfig = {
  http: true,
  template: {
    name: "My MCP Server",
    description: "Describe what your server does.",
    icons: [{ src: "https://example.com/icon.png", mimeType: "image/png" }],
  },
};

export default config;

If your server requires user-provided values (like API keys or configuration settings), you can define a session configuration schema.

For stdio servers, Smithery automatically translates the fields in your JSON schema into command-line arguments using kebab-case format.

Constraints:

• Supported types: string, number, and boolean.
• Maximum of 20 fields allowed.

{
  "type": "object",
  "properties": {
    "apiKey": {
      "type": "string",
      "title": "API Key"
    },
    "model": {
      "type": "string",
      "title": "Model",
      "default": "gpt-4"
    }
  },
  "required": ["apiKey"]
}

Resulting CLI execution:

your-server --api-key=sk-xxx --model=gpt-4

You can use folder names wrapped in parentheses, e.g., (folder), to organize resources into logical groups without affecting the resulting URI. This is useful for separating (public), (private), or (admin) resources.

Example structure:

• src/resources/(public)/docs/api.ts $\rightarrow$ docs://api
• src/resources/(private)/(users)/me/profile.ts $\rightarrow$ users://me/profile

The xmcp application uses a structured approach where components are automatically discovered based on their directory location. To add new functionality, place your files in the following directories:

• src/tools: For tool definitions.
• src/prompts: For prompt templates.
• src/resources: For resource handlers.

To pass complex data from an MCP tool to a rendered widget, return an object containing structuredContent and content.

• structuredContent: A custom object containing the data your widget needs (e.g., game URLs, titles, or configuration).
• content: An array of text objects for the chat interface.

The widget can then access this data using the useToolOutput() hook.

Each resource is uniquely identified by a URI generated from its file path based on specific folder naming conventions:

• URI Scheme: Detected from folders wrapped in parentheses. A folder named (users) creates the users:// scheme.
• Static Segments: Standard folder names become literal path segments.
• Dynamic Parameters: Folders wrapped in brackets [] indicate dynamic parameters in the URI.

Example Mapping: File path: src/resources/(users)/[userId]/profile.ts
Resulting URI: users://{userId}/profile

Decide whether to use React (.tsx) or Template Literals based on the complexity of the widget:

Rule of thumb: If unsure, start with React. Converting from React to template literals later is harder than starting simple.