# xmcp

> xmcp is a framework for building and shipping MCP servers with TypeScript. Designed with DX in mind, it simplifies setup and removes friction in just one command — making it easy to build & deploy AI tools on top of the Model Context Protocol ecosystem.

## Docs

### Getting Started

- [Introduction](/docs): xmcp is a framework for building and shipping MCP servers with TypeScript. Designed with DX in mind, it simplifies setup and removes friction in just one command — making it easy to build & deploy AI tools on top of the Model Context Protocol ecosystem.
- [Installation](/docs/getting-started/installation): Set up your MCP server using automated scaffolding or manual installation, configure build scripts, and troubleshoot transport configurations
- [Connecting to your server](/docs/getting-started/connecting): Configure HTTP and STDIO transport connections for local development and production environments
- [Project structure](/docs/getting-started/project-structure): Explore the file-system based architecture with auto-discovery for tools, prompts, and resources, plus configuration options for custom directory layouts

### Configuration

- [Transports](/docs/configuration/transports): Customize the transport types for your MCP server.
- [Custom Directories](/docs/configuration/custom-directories): Customize where xmcp looks for tools, prompts, and resources.
- [Server Info](/docs/configuration/server-info): Customize the name, description, instructions, icons, and home page of your MCP server.
- [Bundler](/docs/configuration/bundler): Extend the bundler configuration for your MCP server.
- [Telemetry](/docs/configuration/telemetry): A condensed version of the telemetry policy with actionable opt-out instructions.

### Core Concepts

- [Tools](/docs/core-concepts/tools): Tools are functions that your LLM can actively call and decides when to use based on user requests. They enable AI models to perform actions such as writing to databases, calling external APIs, modifying files, or triggering other logic.
- [Request Context](/docs/core-concepts/request-context): Read client identity, HTTP request details, and cancellation state from tool handlers and their async helpers.
- [Prompts](/docs/core-concepts/prompts): Prompts are user-controlled instruction templates that enable structured, consistent interactions through parameterized workflows.
- [Resources](/docs/core-concepts/resources): Resources are application-driven, read-only data sources that provide context to AI models from files, APIs, databases, and other sources.
- [Middlewares](/docs/core-concepts/middlewares): Useful for intercepting and processing requests and responses.
- [CSS](/docs/core-concepts/css): Style your xmcp MCP tools with Tailwind CSS, CSS Modules, or plain CSS, including class management and theming for tool-rendered UI components.
- [External Clients](/docs/core-concepts/external-clients): Learn how to connect to external MCP servers via HTTP or STDIO and generate fully typed TypeScript clients with autocomplete support.

### Authentication

- [API Key](/docs/authentication/api-key): Secure access and protect your MCP server using API keys.
- [JSON Web Token](/docs/authentication/jwt): Secure access and protect your MCP server using JSON Web Tokens.
- [OAuth](/docs/authentication/oauth): Production-ready OAuth implementations with authentication plugins.

### Adapters

- [Next.js](/docs/adapters/nextjs): Plug xmcp into your existing Next.js application.
- [NestJS](/docs/adapters/nestjs): Plug xmcp into your existing NestJS application with automatic tool discovery and customizable module configuration.
- [Express](/docs/adapters/express): Plug xmcp into your existing Express application.
- [Fastify](/docs/adapters/fastify): Run an xmcp MCP server on Fastify. Works on any Node.js deployment target including AWS Lambda.

### Deployment

- [Vercel](/docs/deployment/vercel): Vercel supports xmcp with zero-configuration.
- [Cloudflare](/docs/deployment/cloudflare): Cloudflare Workers support in xmcp uses a Cloudflare-native bundle and Wrangler for local dev and deploy.
- [Alpic](/docs/deployment/alpic): Alpic is a MCP-first cloud platform with one-click deployment for xmcp servers. Deploy your xmcp server to Alpic with zero-configuration.
- [Replit](/docs/deployment/replit): Deploy your xmcp application to Replit with a single click.

### Integrations

- [Auth0](/docs/integrations/auth0): The Auth0 plugin provides authentication for your MCP server using Auth0 with scope-based authorization.
- [Better Auth](/docs/integrations/better-auth): Add secure authentication to your MCP server using Better Auth and PostgreSQL
- [Clerk](/docs/integrations/clerk): The Clerk plugin provides authentication for your MCP server using Clerk's OAuth system.
- [Commet](/docs/integrations/commet): Add subscription-aware billing, feature gating, and usage tracking to your xmcp server with Commet
- [Descope](/docs/integrations/descope): The Descope plugin provides authentication for your MCP server using Descope's OAuth 2.1 agentic identity system with Dynamic Client Registration.
- [Polar](/docs/integrations/polar): Add paywalls and track tool usage with license keys using Polar
- [Scalekit](/docs/integrations/scalekit): The Scalekit plugin provides OAuth 2.1 authentication for your MCP server using Scalekit as the authorization server.
- [WorkOS](/docs/integrations/workos): The WorkOS plugin provides authentication for your mcp server using WorkOS AuthKit.
- [x402](/docs/integrations/x402): The x402 plugin enables tool monetization through the HTTP 402 payment protocol using USDC on Base.

### Discoverability

- [Smithery](/docs/discoverability/smithery): Publish your xmcp server to Smithery for distribution and observability.
- [MCP Server Card](/docs/discoverability/mcp-server-card): Serve an MCP Server Card for automatic agent discovery.

### Guides

- [xmcp MCP server](/docs/guides/xmcp-mcp-server): Connect coding agents to xmcp's documentation MCP server to get real-time answers about xmcp features, configuration, and best practices.
- [Authentication](/docs/guides/authentication): Secure your MCP server with OAuth 2.1, API keys, or JWT tokens. Understand authentication vs authorization, PKCE, scopes, and token-based access control. Integrate with Better Auth, Clerk, Auth0, or WorkOS.
- [Roll out to a team](/docs/guides/roll-out-to-a-team): Roll out secure team access to your xmcp server using Scalekit OAuth 2.1. Understand the team-notes pattern, wire it into your project, and verify per-user isolation.
- [Monetization](/docs/guides/monetization): Charge for your MCP tools using license keys or crypto micropayments. Understand human vs agent monetization models, and integrate with Polar or x402.

## Blog

- [xmcp v1 is here](/blog/xmcp-v1): xmcp v1 splits the compiler out of the runtime, moves to MCP revision 2026-07-28 through SDK v2, and keeps every existing tool, prompt and resource working unchanged.
- [Best MCP Server Frameworks in 2026: TypeScript Edition](/blog/best-mcp-server-frameworks): A practical guide to the main TypeScript frameworks for building MCP servers — the official SDK, FastMCP, Vercel's mcp-handler, and xmcp — with a clear recommendation for each use case.
- [How to Deploy an MCP Server to Production (Vercel, Lambda, Railway)](/blog/deploy-mcp-server-production): A practical comparison of the main MCP server deployment targets — Vercel, AWS Lambda, Railway, and ECS — with the tradeoffs for each and how xmcp simplifies the Vercel path.
- [Best FastMCP Alternatives for TypeScript MCP Servers (2026)](/blog/fastmcp-alternatives): Looking for alternatives to FastMCP? Here's how the main TypeScript MCP frameworks compare — and when xmcp, the official SDK, or Vercel's mcp-handler might be a better fit.
- [How to Debug Your MCP Server (MCP Inspector Guide)](/blog/how-to-debug-mcp-server): MCP servers fail silently in ways that REST APIs don't. Here's how to use the MCP Inspector to test tools, catch protocol errors, and diagnose the most common issues.
- [How to Monetize Your MCP Server (x402 and Polar)](/blog/how-to-monetize-mcp-server): Two practical approaches to charging for MCP tool usage: x402 for per-call micropayments and Polar for subscription-based access — both built into xmcp.
- [MCP Elicitation: How AI Agents Ask Users for Input Mid-Task](/blog/mcp-elicitation-explained): Elicitation is an MCP primitive that lets a server pause a tool call and ask the user a structured question — without routing the request through the AI model. Here's how it works and when to use it.
- [How to Add Authentication to Your MCP Server](/blog/mcp-server-authentication): A practical guide to securing MCP server tools with OAuth 2.0 — and how xmcp's auth plugins (Better Auth, Clerk, Auth0, WorkOS, Scalekit) make it straightforward.
- [MCP Server: Python vs TypeScript (Which Should You Use?)](/blog/mcp-server-python-vs-typescript): Both Python and TypeScript have official MCP SDKs. Here's how they compare on type safety, ecosystem, tooling, and the path to production — and why TypeScript is the stronger default for most teams.
- [MCP Tools vs Resources vs Prompts: When to Use Each](/blog/mcp-tools-vs-resources-vs-prompts): MCP servers can expose three types of capabilities: tools, resources, and prompts. They're not interchangeable — each one is controlled by a different actor and used for a different purpose.
- [MCP vs OpenAI Function Calling: Key Differences Explained](/blog/mcp-vs-openai-function-calling): OpenAI function calling and MCP both let AI models invoke external code — but they solve different problems. Here's how they compare and when to use each.
- [MCP Server vs REST API: When to Use Each](/blog/mcp-vs-rest-api): MCP servers and REST APIs both expose functionality over a network — but they're designed for different clients. Here's when to build each one, and when you need both.
- [MCP Clients Explained: Claude, Cursor, and the Growing Ecosystem](/blog/what-are-mcp-clients): An MCP server is only half the picture — here's a guide to the clients (Claude Desktop, Cursor, GitHub Copilot, and others) that connect to MCP servers, and how each one works.
- [xmcp vs Vercel mcp-handler: Which MCP Solution Is Right for You?](/blog/xmcp-vs-mcp-handler): A focused comparison of xmcp and Vercel's mcp-handler — two very different takes on MCP in TypeScript. One is a standalone framework; the other bolts MCP onto an existing Next.js or Nuxt app.
- [How to Build an MCP Server in TypeScript (2026 Guide)](/blog/build-mcp-server-typescript): A step-by-step guide to building a Model Context Protocol (MCP) server in TypeScript with xmcp: scaffold a project, write your first tool, run it locally, and connect it to Claude or Cursor.
- [Fix: MCP Server Won't Connect in Claude Desktop](/blog/fix-mcp-server-claude-desktop-connection): A troubleshooting checklist for when your MCP server won't connect in Claude Desktop — transport mismatches, the mcp-remote bridge, STDIO logging, CORS, and config file mistakes.
- [MCP Transports Explained: STDIO vs SSE vs Streamable HTTP](/blog/mcp-server-transports-explained): A clear breakdown of MCP server transports — STDIO, the legacy HTTP+SSE transport, and Streamable HTTP — when to use each, and how xmcp configures them with a single line.
- [MCP "Session not found" (HTTP 404): Causes & Fixes](/blog/mcp-session-not-found-error): Why MCP clients get an HTTP 404 'Session not found' after an MCP server restarts or redeploys, what's actually happening with the Mcp-Session-Id, and how a stateless server design avoids it.
- [What Is an MCP Server? A Plain-English Guide](/blog/what-is-an-mcp-server): An MCP server exposes tools, resources, and prompts to AI clients over the Model Context Protocol. Here's what that means, why it matters, and how to build one with xmcp.
- [When your agent has to pay](/blog/paying-for-mcp-tools-with-x402): Charging for a tool is the easy half. The real shift is software that pays for tools on its own — how x402 lets agents settle USDC micropayments per call.
- [Integrating NestJS with xmcp](/blog/nestjs-integration): Add an MCP server to your NestJS application with tool discovery and a customizable module.
- [Pay-per-use MCP tools with x402](/blog/x402-integration): Charge per tool call using x402 crypto micropayments with USDC on Base — gate your MCP tools behind HTTP 402 payment-required middleware.
- [How to build an MCP App](/blog/mcp-apps): Learn how to build an MCP App with xmcp — ship interactive React widgets, tool-rendered UIs, and ChatGPT-compatible resources with out-of-the-box support.
- [Securing Your MCP Server](/blog/securing-your-mcp-server): A practical guide to authentication for MCP servers: when you need it, how it works, and which approach fits your use case.
- [When tools need UIs](/blog/react-client-components): Our philosophy on bringing UI components to MCP tools — when tools need interfaces, how React widgets render inside ChatGPT, and what we chose to ship.
- [How to submit your GPT app](/blog/build-and-submit-gpt-apps): A complete guide to submitting your ChatGPT App to the OpenAI directory — prepare your GPT, complete review requirements, and ship to production.
- [Everything we shipped so far](/blog/everything-we-shipped-so-far): From GPT apps and React components to external MCP clients, OAuth, and monetization — a recap of everything we shipped across xmcp this year.
- [Monetize your GPT apps with Stripe](/blog/apps-monetization): Learn how to monetize your GPT apps with Stripe external checkout — set up paywalls, handle payments server-side, and gate tools behind successful charges.
- [Running DOOM in ChatGPT: A Step-by-Step Guide](/blog/doom-with-xmcp): Learn how we made DOOM playable inside ChatGPT using xmcp — rendering frames as images, streaming inputs, and shipping an MCP-powered game loop.
- [Connect to external MCPs and make their tools yours](/blog/cli-typed-clients): Generate fully typed TypeScript MCP clients from remote HTTP servers or STDIO packages with one xmcp command, with autocomplete for tools and prompts.
- [OpenAI Apps SDK Support](/blog/apps-sdk): xmcp now supports building UI resources and tools compatible with the OpenAI Apps SDK out of the box — ship ChatGPT apps without custom rendering code.
- [Integrating Polar with xmcp](/blog/polar-integration): Learn how to add paywalls and track per-tool usage with Polar license keys in xmcp — gating tools, subscriptions, and metered billing for MCP servers.
- [xmcp v0.3.0 — Tools, Prompts, and Resources](/blog/v0.3.0-release): xmcp v0.3.0 ships full MCP server coverage — tools, prompts, and resources — plus auth, transports, and adapter improvements. Available now.
- [Deploy to Vercel with zero-configuration](/blog/vercel-zero-config): Kick off your xmcp project instantly with the Vercel template — zero-configuration deploys, instant previews on every push, and serverless MCP hosting.
- [Integrating Better Auth with xmcp](/blog/better-auth-integration): Learn how to add secure authentication to your xmcp MCP server using Better Auth with PostgreSQL — sessions, account linking, and OAuth 2.1 providers.

## Templates

- [Auth0 Authentication](/templates/auth0): An MCP server with Auth0 authentication and tools to interact with Auth0 client.
- [Clerk Authentication](/templates/clerk): An MCP server with Clerk authentication, session data and organization management
- [Express Starter](/templates/express): An Express MCP server using xmcp's adapter
- [Fastify Starter](/templates/fastify): A Fastify MCP server using xmcp's adapter
- [GPT Monetization with Stripe](/templates/gpt-monetization): A Next.js + MCP application for monetizing ChatGPT apps using Stripe
- [MCP App with React Widgets](/templates/mcp-app): An MCP server with React widgets and Tailwind CSS styling using MCP Apps
- [NestJS Starter](/templates/nestjs): A NestJS MCP server using xmcp's adapter
- [Next.js Starter](/templates/nextjs): A full-stack MCP server built with Next.js and xmcp
- [React Widgets](/templates/react): An MCP server with interactive React component widgets
- [Scalekit Authentication](/templates/scalekit): An MCP server with Scalekit authentication for B2B organizations. Per-user and per-org data isolation with optional RBAC.
- [xmcp TypeScript Starter](/templates/typescript): Baseline xmcp template with typed tools, prompts, and resources using HTTP transport.
- [WorkOS AuthKit](/templates/workos): An MCP server with WorkOS AuthKit authentication
- [x402 Monetization](/templates/x402): An MCP server with x402 payment middleware for USDC micropayments

## FAQ

- [What is xmcp?](/faq#what-is-xmcp)
- [How do I create a new xmcp project?](/faq#create-a-project)
- [What are tools, resources, and prompts in xmcp?](/faq#tools-resources-and-prompts)
- [How do I define a tool in xmcp?](/faq#define-a-tool)
- [What transport options does xmcp support?](/faq#transports)
- [Is xmcp's HTTP transport stateful or stateless?](/faq#stateless-http)
- [Which frameworks can I integrate xmcp with?](/faq#framework-integrations)
- [How do I add authentication to an xmcp server?](/faq#authentication)
- [Where can I deploy an xmcp server?](/faq#deployment)
- [Can I charge for MCP tools built with xmcp?](/faq#monetization)
- [How do I make my xmcp server discoverable to LLMs and registries?](/faq#discoverability)
- [Is xmcp open source?](/faq#open-source)
- [What is the Model Context Protocol (MCP)?](/faq#what-is-mcp)
- [Why use xmcp instead of building an MCP server from scratch?](/faq#why-xmcp)

## Pages

- [Showcase](/showcase): community MCP servers built with xmcp
- [Telemetry](/telemetry): what anonymous telemetry xmcp collects and how to opt out

## Optional

- [llms-full.txt](/llms-full.txt): complete documentation and blog content in one file
- [index.md](/index.md): site overview in markdown
- [blog.md](/blog.md): blog index in markdown
- [templates.md](/templates.md): templates index in markdown
- [faq.md](/faq.md): frequently asked questions with full answers in markdown