Skip to main content

​
Get started in three steps

This guide will walk you through creating your first xmcp application, implementing a tool, and testing it.
1

Create your xmcp app

Bootstrap a new xmcp application using the CLI:
npx create-xmcp-app@latest my-first-app
Follow the prompts to configure your project. For this quickstart, select the TypeScript template.Navigate to your project directory:
cd my-first-app
2

Create your first tool

Create a new file src/tools/greet.ts with the following code:
src/tools/greet.ts
import { z } from "zod";
import { type InferSchema, type ToolMetadata } from "xmcp";

// Define the schema for tool parameters
export const schema = {
  name: z.string().describe("The name of the user to greet"),
};

// Define tool metadata
export const metadata: ToolMetadata = {
  name: "greet",
  description: "Greet the user",
  annotations: {
    title: "Greet the user",
    readOnlyHint: true,
    destructiveHint: false,
    idempotentHint: true,
  },
};

// Tool implementation
export default async function greet({ name }: InferSchema<typeof schema>) {
  const result = `Hello, ${name}!`;

  return {
    content: [{ type: "text", text: result }],
  };
}
What’s happening here?
  • schema: Defines the input parameters using Zod for validation
  • metadata: Provides information about the tool for MCP clients
  • default export: The tool implementation that returns content
3

Start the development server

Run the xmcp development server with hot reloading:
npm run dev
You should see output indicating your server is running:
xmcp dev server starting...
✓ Tools registered: greet
✓ Server ready
The dev server watches for file changes and automatically reloads when you modify your tools.
4

Test your tool

Your tool is now ready to be used by any MCP client. You can test it using:

​
Using the MCP Inspector

The MCP Inspector is a great tool for testing your MCP server:
  1. Install the MCP Inspector: 
    npm install -g @modelcontextprotocol/inspector
  2. Run the inspector: 
    mcp-inspector
  3. Connect to your xmcp server and test the greet tool

​
Using Claude Desktop

To use your tool with Claude Desktop:
  1. Open Claude Desktop configuration: 
    # macOS
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows
notepad %APPDATA%\Claude\claude_desktop_config.json
  2. Add your xmcp server: 
    {
  "mcpServers": {
    "my-first-app": {
      "command": "node",
      "args": ["/path/to/my-first-app/dist/index.js"]
    }
  }
}
  3. Restart Claude Desktop and ask it to greet someone

​
Understanding the Tool Structure

Every xmcp tool follows this pattern:

​
1. Schema Definition

Define your tool’s input parameters using Zod: 
export const schema = {
  name: z.string().describe("The name of the user to greet"),
  age: z.number().optional().describe("The user's age"),
};

​
2. Metadata

Provide metadata about your tool: 
export const metadata: ToolMetadata = {
  name: "greet",
  description: "Greet the user",
  annotations: {
    title: "Greet the user",
    readOnlyHint: true,      // Tool doesn't modify data
    destructiveHint: false,  // Tool is not destructive
    idempotentHint: true,    // Same input = same output
  },
};

​
3. Implementation

Implement your tool logic: 
export default async function greet({ name, age }: InferSchema<typeof schema>) {
  const greeting = age 
    ? `Hello, ${name}! You are ${age} years old.`
    : `Hello, ${name}!`;

  return {
    content: [{ type: "text", text: greeting }],
  };
}

​
Add More Tools

Adding more tools is as simple as creating new files in the src/tools directory. Create src/tools/random-number.ts:
src/tools/random-number.ts
import { type ToolMetadata } from "xmcp";

export const metadata: ToolMetadata = {
  name: "random-number",
  description: "Generate a random number",
};

export default async function randomNumber() {
  const result = Math.random();
  return {
    content: [{ type: "text", text: result.toString() }],
  };
}
xmcp automatically discovers and registers all tools in the src/tools directory. No manual registration required!

​
Next Steps

Congratulations! You’ve built your first xmcp application. Here’s what to explore next:

Core Concepts

Learn about tools, prompts, and resources

Middleware

Add authentication and custom logic

Configuration

Customize your xmcp server

Deployment

Deploy your app to production

​
Examples

Explore more examples in the xmcp GitHub repository:
  • with-express: Integration with Express.js
  • with-nextjs: Integration with Next.js
  • with-nestjs: Integration with NestJS
  • middlewares-api-key: API key authentication
  • http-transport: HTTP transport examples
Need help? Join the community or report issues on GitHub.

Build docs developers (and LLMs) love

Get started for freeTalk to us