📌Overview

Purpose: FastMCP is a TypeScript framework for building MCP servers that effectively manage client sessions.

Overview: FastMCP simplifies the development of MCP servers by providing an intuitive interface for defining tools, managing sessions, and handling client interactions via various transport methods, including SSE. It is designed to facilitate seamless communication between clients and servers.

Key Features:

Simple Tool and Resource Definition: Easily create and manage executable functions and resources that clients can access.
Authentication: Implement custom client authentication mechanisms to safeguard server interactions.
Sessions Management: Supports dedicated sessions for each client, enabling personalized communication and state management.
SSE and Real-time Communication: Built-in support for Server-Sent Events (SSE) to facilitate real-time updates between server and clients.
Progress Notifications and Error Handling: Features like progress reporting and user-friendly error handling enhance user experience and debugging.

FastMCP

A TypeScript framework for building MCP servers capable of handling client sessions.

Features

Simple Tool, Resource, Prompt definitions
Authentication
Sessions
Logging
Error handling
SSE (Server-Sent Events)
CORS (enabled by default)
Progress notifications
Typed server events
Prompt argument auto-completion
Sampling
Automated SSE pings
CLI for testing and debugging

Installation

npm install fastmcp

Quickstart

import { FastMCP } from "fastmcp";
import { z } from "zod";

const server = new FastMCP({
  name: "My Server",
  version: "1.0.0",
});

server.addTool({
  name: "add",
  description: "Add two numbers",
  parameters: z.object({
    a: z.number(),
    b: z.number(),
  }),
  execute: async (args) => {
    return String(args.a + args.b);
  },
});

server.start({
  transportType: "stdio",
});

Testing the Server

In the terminal, run:

git clone https://github.com/punkpeye/fastmcp.git
cd fastmcp
npm install
npx fastmcp dev src/examples/addition.ts
npx fastmcp inspect src/examples/addition.ts

SSE Support

To run the server with SSE support:

server.start({
  transportType: "sse",
  sse: {
    endpoint: "/sse",
    port: 8080,
  },
});

Core Concepts

Tools

Tools in MCP allow servers to expose executable functions:

server.addTool({
  name: "fetch",
  description: "Fetch the content of a URL",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    return await fetchWebpageContent(args.url);
  },
});

Logging

Tools can log messages using the log context:

server.addTool({
  name: "download",
  description: "Download a file",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args, { log }) => {
    log.info("Downloading file...", { url });
    log.info("Downloaded file");
    return "done";
  },
});

Authentication

Authenticate clients with a custom function:

const server = new FastMCP({
  name: "My Server",
  version: "1.0.0",
  authenticate: ({ request }) => {
    const apiKey = request.headers["x-api-key"];
    if (apiKey !== '123') {
      throw new Response(null, { status: 401, statusText: "Unauthorized" });
    }
    return { id: 1 };
  },
});

Sessions

Access active client sessions:

server.sessions;

Typed Server Events

Listen for events emitted by the server:

server.on("connect", (event) => {
  console.log("Client connected:", event.session);
});

Running Your Server

Testing with `mcp-cli`

Run your server with:

npx fastmcp dev server.js

Inspecting with `MCP Inspector`

Inspect your server with:

npx fastmcp inspect server.ts

FAQ

How to use with Claude Desktop?

Follow the guide and add the following configuration:

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "npx",
      "args": ["tsx", "/PATH/TO/YOUR_PROJECT/src/index.ts"],
      "env": { "YOUR_ENV_VAR": "value" }
    }
  }
}

Showcase

If you've developed a server using FastMCP, please submit a PR to showcase it here!

Acknowledgements

FastMCP is inspired by the Python implementation by Jonathan Lowin.
Parts of the codebase were adopted from LiteMCP and various articles on the Model Context protocol.

fastmcp