punkpeye/fastmcp

FastMCP – Quick Overview

What it is – FastMCP is a TypeScript framework for building servers that speak the Model Context Protocol (MCP). MCP is a protocol that lets LLMs (or other AI agents) call tools, fetch resources, and exchange structured data with a backend server. FastMCP wraps the official MCP SDK and adds a lot of plumbing so you can focus on defining tools, resources, prompts, etc.

Key capabilities

• Define tools, resources, and prompts with a simple, typed API (supports Zod, ArkType, Valibot, or raw JSON‑Schema).
• Built‑in authentication, session & request‑ID tracking, and error handling.
• Multiple transport options:
  • stdio (for local CLI use)
  • HTTP streaming (efficient binary‑friendly streaming, also provides an SSE fallback)
  • HTTPS with custom certs, CORS configuration, and health‑check endpoint.
• Custom HTTP routes via the underlying Hono app – you can expose REST APIs, webhooks, admin pages, etc., alongside the MCP endpoint.
• Edge runtime support – a lightweight EdgeFastMCP class lets you run the same server on Cloudflare Workers, Deno Deploy, etc. (stateless only on the edge).
• Stateless mode for serverless deployments – each request gets a temporary session, no persistent state kept.
• Convenience features: progress notifications, streaming output, typed server events, auto‑completion for prompt arguments, sampling/elicitation controls, configurable ping, in‑memory transport for unit tests, and a CLI (fastmcp dev, fastmcp inspect).

When to use it – Choose FastMCP if you want a ready‑made MCP server without writing the low‑level socket handling that the official SDK requires. It’s ideal for rapid prototyping or production services that need authentication, HTTPS, custom routes, or edge deployment. If you need full control over every detail, the raw SDK may still be preferable.

Typical workflow

1. npm install fastmcp
2. Create a FastMCP instance with basic metadata.
3. Add tools/resources using server.addTool(...) etc., providing a schema (Zod, etc.) and an async execute function.
4. Call server.start({ transportType: "httpStream", httpStream: { port: 8080 } }) (or stdio for CLI).
5. Optionally add custom Hono routes via server.getApp() for REST endpoints or webhooks.
6. Deploy – run on a Node server, or switch to EdgeFastMCP and deploy to Cloudflare Workers.

Example snippet (from the README) shows a tiny addition tool that can be run locally with npx fastmcp dev src/examples/addition.ts.

---

Quick Reference

• Package: fastmcp (npm)
• Language: TypeScript
• Primary runtime: Node.js (EdgeFastMCP for Cloudflare Workers, Deno Deploy)
• Transport options: stdio, httpStream (with optional HTTPS), SSE fallback
• Authentication: pluggable authenticate callback; works with API keys, OAuth, etc.
• Testing: in‑memory transport, CLI dev mode, inspector UI.

---

Bottom line – FastMCP is a genuine, production‑ready framework for building MCP‑based AI service back‑ends, handling the protocol details, security, and deployment concerns so developers can concentrate on the AI‑specific logic.