diff --git a/mcp/assets/building-mcp-server-for-fastapi-with-fastmcp/claude-creating-a-burger.png b/mcp/assets/building-mcp-server-for-fastapi-with-fastmcp/claude-creating-a-burger.png
new file mode 100644
index 00000000..fc78b8aa
Binary files /dev/null and b/mcp/assets/building-mcp-server-for-fastapi-with-fastmcp/claude-creating-a-burger.png differ
diff --git a/mcp/assets/building-mcp-server-for-fastapi-with-fastmcp/fastmcp-installing-mcp-server.png b/mcp/assets/building-mcp-server-for-fastapi-with-fastmcp/fastmcp-installing-mcp-server.png
new file mode 100644
index 00000000..e8afd3a9
Binary files /dev/null and b/mcp/assets/building-mcp-server-for-fastapi-with-fastmcp/fastmcp-installing-mcp-server.png differ
diff --git a/mcp/assets/building-mcp-server-for-fastapi-with-fastmcp/mcp-server-fastmcp-claude-listing-tools.png b/mcp/assets/building-mcp-server-for-fastapi-with-fastmcp/mcp-server-fastmcp-claude-listing-tools.png
new file mode 100644
index 00000000..ed77502c
Binary files /dev/null and b/mcp/assets/building-mcp-server-for-fastapi-with-fastmcp/mcp-server-fastmcp-claude-listing-tools.png differ
diff --git a/mcp/assets/building-mcp-server-for-fastapi-with-fastmcp/mcp-server-fastmcp-claude.png b/mcp/assets/building-mcp-server-for-fastapi-with-fastmcp/mcp-server-fastmcp-claude.png
new file mode 100644
index 00000000..354621c3
Binary files /dev/null and b/mcp/assets/building-mcp-server-for-fastapi-with-fastmcp/mcp-server-fastmcp-claude.png differ
diff --git a/mcp/assets/building-mcp-server-for-fastapi-with-fastmcp/mcp-server-search-and-tools-button.png b/mcp/assets/building-mcp-server-for-fastapi-with-fastmcp/mcp-server-search-and-tools-button.png
new file mode 100644
index 00000000..9a7253fe
Binary files /dev/null and b/mcp/assets/building-mcp-server-for-fastapi-with-fastmcp/mcp-server-search-and-tools-button.png differ
diff --git a/mcp/assets/building-mcp-server-for-fastapi-with-fastmcp/mcp-typescript-sdk.png b/mcp/assets/building-mcp-server-for-fastapi-with-fastmcp/mcp-typescript-sdk.png
new file mode 100644
index 00000000..acc94329
Binary files /dev/null and b/mcp/assets/building-mcp-server-for-fastapi-with-fastmcp/mcp-typescript-sdk.png differ
diff --git a/mcp/assets/building-mcp-server-for-fastapi-with-fastmcp/speakeasy-choosing-sdk-name.png b/mcp/assets/building-mcp-server-for-fastapi-with-fastmcp/speakeasy-choosing-sdk-name.png
new file mode 100644
index 00000000..ce21a4f5
Binary files /dev/null and b/mcp/assets/building-mcp-server-for-fastapi-with-fastmcp/speakeasy-choosing-sdk-name.png differ
diff --git a/mcp/assets/building-mcp-server-for-fastapi-with-fastmcp/speakeasy-choosing-sdk-type.png b/mcp/assets/building-mcp-server-for-fastapi-with-fastmcp/speakeasy-choosing-sdk-type.png
new file mode 100644
index 00000000..dd6f3e50
Binary files /dev/null and b/mcp/assets/building-mcp-server-for-fastapi-with-fastmcp/speakeasy-choosing-sdk-type.png differ
diff --git a/mcp/assets/building-mcp-server-for-fastapi-with-fastmcp/speakeasy-openapi-path.png b/mcp/assets/building-mcp-server-for-fastapi-with-fastmcp/speakeasy-openapi-path.png
new file mode 100644
index 00000000..0ebf1878
Binary files /dev/null and b/mcp/assets/building-mcp-server-for-fastapi-with-fastmcp/speakeasy-openapi-path.png differ
diff --git a/mcp/building-mcp-server-for-fastapi-with-fastmcp.mdx b/mcp/building-mcp-server-for-fastapi-with-fastmcp.mdx
new file mode 100644
index 00000000..2b4ac575
--- /dev/null
+++ b/mcp/building-mcp-server-for-fastapi-with-fastmcp.mdx
@@ -0,0 +1,414 @@
+---
+title: "Building an MCP server for your FastAPI API with FastMCP"
+description: "A guide to building an MCP server for your FastAPI API using FastMCP and Speakeasy, comparing the two tools on maintainability, code quality, and usage."
+---
+
+import { Callout } from "@/mdx/components";
+import { Screenshot } from "@/mdx/components";
+
+Because Model Context Protocol (MCP) servers enable communication with APIs, they allow a range of possible integrations, such as placing orders using Claude or helping developers understand your API using Cursor AI.
+
+But let's be honest. Writing an MCP server from scratch with API integrations while you already have your controllers in place or an OpenAPI document is tedious. With FastMCP and Speakeasy, you can generate an MCP server directly from a ready-made API, removing the need to rewrite logic or duplicate schemas, making your backend instantly agent-ready.
+
+This guide will compare two approaches to building an MCP server for a [FastAPI](https://fastapi.tiangolo.com/) API using different tools. The first approach uses [FastMCP](https://gofastmcp.com/getting-started/welcome), while the second uses [Speakeasy](https://www.speakeasy.com/). The guide will focus on comparing the maintenance, code quality, and usage of these two tools.
+
+## Requirements
+
+Let's build an MCP server using the [APItizing Burgers example app](https://github.com/speakeasy-api/examples/tree/main/fastmcp-speakeasy-project/base).
+
+Clone the project with the following command:
+
+```bash
+git clone https://github.com/speakeasy-api/examples
+cd examples/fastmcp-speakeasy-project/base
+```
+
+To make the setup easier, use the `uv` environment manager. You can use any Python environment creation tool.
+
+```bash
+uv venv
+source .venv/bin/activate
+```
+
+Then, install the required dependencies for the project. Because the `apitizing-burger` project is already set up with FastAPI, you can jump to installing the FastAPI package and its dependencies.
+
+```bash
+uv pip install "fastapi[all]"
+```
+
+Run the API using the following command:
+
+```bash
+uvicorn app.main:server --reload
+```
+
+It's a good idea to have [Claude](https://claude.ai/download) installed on your device to test the MCP servers. Then, you can start integrating FastMCP and Speakeasy in the project to build an MCP server.
+
+Let's begin by integrating FastMCP.
+
+## Building an MCP server with FastAPI and FastMCP
+
+FastMCP is a Python package that provides a high-level implementation of the MCP Python software development kit (SDK). By using this package, you can quickly build an MCP server without worrying about the low-level implementation of component lifecycle management, including tools, resources, or prompts.
+
+Interestingly, the FastMCP package provides an [integration with FastAPI](https://gofastmcp.com/servers/openapi#fastapi-integration) that transforms your controllers into MCP tools. Here's how to implement it:
+
+### 1. Install FastMCP
+
+First, install the [FastMCP](https://github.com/jlowin/fastmcp?tab=readme-ov-file#installation) package in the project.
+
+```bash
+uv pip install fastmcp
+```
+
+### 2. Create the MCP server file
+
+Create a file in the `app` directory called `mcp_server.py`. This file will contain the code for the MCP server.
+
+```bash
+cd app/ && touch mcp_server.py
+```
+
+### 3. Configure FastMCP with FastAPI
+
+Inside the `mcp_server.py` file, add the below code. This is how you register your FastAPI app with FastMCP using a single line. From there, FastMCP inspects the app, identifies the declared controllers in `app/main.py`, and converts each route into an MCP tool without requiring any additional configuration.
+
+```python
+from fastmcp import FastMCP
+from app.main import server
+
+# Create an MCP server from your FastAPI app
+mcp = FastMCP.from_fastapi(app=server)
+
+if __name__ == "__main__":
+ mcp.run()
+```
+
+### 4. Install the MCP server in the Claude desktop app
+
+There's no need to write the configuration yourself. Instead, go into the `app` directory and run the `fastmcp install` command to handle the installation:
+
+```bash
+fastmcp install mcp_server.py
+```
+
+You'll get a similar output, confirming that the MCP server is installed in Claude.
+
+
+
+The configuration won't work just yet. Let's have a look at the `claude-desktop-config.json` file.
+
+
+Find the configuration file by going to Settings -> Developer -> Edit config in Claude Desktop.
+
+
+```json
+{
+ "mcpServers": {
+ "mcp_server": {
+ "command": "uv",
+ "args": [
+ "run",
+ "--with",
+ "fastmcp",
+ "fastmcp",
+ "run",
+ "path/to/project/fastmcp-speakeasy-project/base/app/mcp_server.py"
+ ]
+ }
+ }
+}
+```
+
+The `--with` option lets you specify the dependencies to use when running the file. However, `fastmcp` is not the only dependency, as you are also working with `fastapi`. You may encounter issues with the Python path, which can result in import errors. Modify the configuration by adding the `fastapi[all]` dependency and an environment variable to set the Python path, ensuring Claude can run the project without issues.
+
+```json
+{
+ "mcpServers": {
+ "mcp_server": {
+ "command": "uv",
+ "args": [
+ "run",
+ "--with",
+ "fastmcp",
+ "--with",
+ "fastapi[all]",
+ "fastmcp",
+ "run",
+ "path/to/project/fastmcp-speakeasy-project/base/app/mcp_server.py"
+ ],
+ "env": {
+ "PYTHONPATH": "path/to/project/fastmcp-speakeasy-project/base/"
+ }
+ }
+ }
+}
+```
+
+The integration of FastAPI and FastMCP is now complete, and you can test the MCP server in the Claude desktop app.
+
+### Test the integration
+
+Open your Claude desktop app and click on the **Search and tools** button.
+
+
+
+Clicking on the **Search and tools** button will display the MCP servers installed. Your MCP server's name will be `mcp_server`.
+
+
+
+
+Click on the server to see the tools you added.
+
+
+
+
+You can then ask Claude to create a burger in the chat. In the screenshot below, you can see that Claude made a tool call to create a burger from our API.
+
+
+
+You have now created an MCP server with FastAPI and FastMCP.
+
+### More configuration with FastMCP
+
+FastMCP gives you some flexibility in how tools display. You can configure things like the server name, timeout values, custom tool names, and route maps to control which endpoints are included or excluded.
+
+Here's an example that renames the server, overrides a tool name, and excludes the route for deleting a burger:
+
+```python
+mcp = FastMCP.from_fastapi(
+ app=server,
+ name="Apitizer MCP Server",
+ timeout=5.0,
+ mcp_names={"createBurger": "Create a burger menu"},
+ route_maps=[
+ # Exclude delete burger route
+ RouteMap(methods="DELETE", pattern=r".*", mcp_type=MCPType.EXCLUDE, tags={"burger"}),
+ ],
+ )
+```
+
+### Considerations for FastMCP in FastAPI
+
+FastMCP avoids code duplication by reusing your existing FastAPI endpoints. Typing and schema definitions are preserved, including inheritance and Pydantic validations. This preservation also extends to dependencies, middleware, and authentication, all of which carry over into the MCP layer.
+
+FastMCP behaves like a black box. You get speed and simplicity, but not much visibility into how tools, prompts, or resources are constructed. In contrast, when you use the MCP Python SDK directly – even with FastMCP – you build things manually but retain full control. You can interact with the component lifecycle, adjust behavior, and trace execution more easily.
+
+Without visibility, debugging tool behavior can be difficult to manage when something breaks or doesn't work as expected.
+
+## Building an MCP server with FastAPI and Speakeasy
+
+[Speakeasy](https://www.speakeasy.com/) is a tool and service that helps you generate SDKs from OpenAPI documents in a range of languages. Speakeasy supports [generating MCP servers](https://www.speakeasy.com/docs/model-context-protocol) alongside your SDK code (currently only for TypeScript SDKs, with support for additional languages planned). All you need is an OpenAPI document and a [Speakeasy account](https://www.speakeasy.com/docs/introduction#sign-up).
+
+Let's build an MCP server with FastAPI and Speakeasy.
+
+### 1. Install the Speakeasy CLI
+
+Install [Speakeasy](https://www.speakeasy.com/docs/introduction#install-the-speakeasy-cli) on your device. If you are using a Mac or Linux, use the following commands:
+
+```bash
+# Homebrew (macOS)
+brew install speakeasy-api/homebrew-tap/speakeasy
+
+# or script Installation (macOS and Linux)
+curl -fsSL https://go.speakeasy.com/cli-install.sh | sh
+```
+
+If you are using a Windows device, use the following commands:
+
+```bash
+# Windows Installation
+# Using winget:
+winget install speakeasy
+
+# or Using Chocolatey:
+choco install speakeasy
+```
+
+### 2. Upload the OpenAPI document
+
+The APItizing Burgers project already has OpenAPI document files like `openapi.yaml` and `openapi.json`, and there's no need to perform any configuration for them.
+
+
+You will need to generate some files for your FastAPI project. Follow [this tutorial](/openapi/frameworks/fastapi#basic-fastapi-setup) on how to generate a quality OpenAPI document for your FastAPI project.
+
+
+
+To start the process, run the following command from the project's root directory:
+
+```bash
+speakeasy quickstart
+```
+
+This command will prompt for authentication. After authenticating successfully, enter the following path to the OpenAPI document: `./openapi.yaml`.
+
+
+
+
+### 3. Name the SDK
+
+Name the SDK `mcp-burger-sdk`.
+
+
+
+
+### 4. Select the output
+
+Speakeasy will ask what you want to generate. Choose **Model Context Protocol (MCP) Server**, and then the sub-option **TypeScript SDK with Server**.
+
+
+
+The Speakeasy command-line interface (CLI) will then ask for a directory to generate the SDK and a name for the npm package. Press **Enter** to use the current directory and the default package name, or modify them if needed.
+
+At this stage, Speakeasy will generate a TypeScript SDK in the `mcp-burger-sdk-typescript` directory. The MCP server code will be located at `mcp-burger-sdk-typescript/src/mcp-server`. A built version is also available at `mcp-burger-sdk-typescript/bin/mcp-server.js`, which is the file you'll reference in your Claude configuration.
+
+### 5. Install the MCP Server in the Claude desktop app
+
+With the MCP server already built, the next step is to configure the MCP server in the `claude-desktop-config.json` file.
+
+```json
+{
+ "mcpServers": {
+ "McpBurgerSDK": {
+ "command": "node",
+ "args": [
+ "path/to/mcp-burger-sdk-typescript/bin/mcp-server.js",
+ "start"
+ ]
+ }
+ }
+}
+```
+
+
+ Speakeasy allows you to install your MCP server after it has been published to the npm registry. To do this, you would use a similar configuration in the `claude-desktop-config.json` file.
+
+```json
+{
+ "mcpServers": {
+ "McpBurgerSDK": {
+ "command": "npx",
+ "args": [
+ "-y",
+ "--package",
+ "mcp-burger-sdk",
+ "--",
+ "mcp",
+ "start",
+ "--api-key",
+ "..."
+ ]
+ }
+ }
+}
+```
+
+
+Once the installation is complete, reload the Claude desktop app. You should see the server and its available tools.
+
+
+
+You now have a working MCP server generated with Speakeasy.
+
+### More configuration with Speakeasy
+
+Speakeasy allows you to [customize](https://www.speakeasy.com/docs/model-context-protocol#configuration-options) your server, whether you'd like to hide certain tools and set specific scopes, but the customization starts with the OpenAPI document. To disable the generation of a tool for an operation, use the `x-speakeasy-mcp` extension.
+
+```yaml
+paths:
+ /products:
+ post:
+ operationId: createProduct
+ tags: [products]
+ summary: Create a product
+ description: API endpoint for creating a product in the CMS
+ x-speakeasy-mcp:
+ disabled: false
+ name: create-product
+ scopes: [products, create, ecommerce]
+ description: |
+ Creates a new product using the provided form. The product name should
+ not contain any special characters or harmful words.
+```
+
+In the code configuration above:
+
+- `disabled` specifies when a tool should be ignored.
+- `name` is used to set the name of the MCP tool if you want to change it.
+- `scopes` are a way of tagging tools, which is helpful when you want to run the MCP server for a specific set of tools.
+
+When starting the MCP server with Speakeasy, you can specify which scopes to include with the `--scope` flag:
+
+```json
+{
+ "mcpServers": {
+ "EcommerceSDK": {
+ "command": "npx",
+ "args": [
+ "-y",
+ "--package",
+ "e-commerce-sdk",
+ "mcp",
+ "start",
+ "--scope",
+ "products"
+ ],
+ "env": {
+ "API_TOKEN": "your-api-token-here"
+ }
+ }
+ }
+}
+```
+
+If modifying the OpenAPI document is a hassle, you can use [Overlays](https://www.speakeasy.com/openapi/overlays), which provides a convenient way to apply the `x-speakeasy-mcp` extension without changing the original file. The code below instructs Speakeasy to generate tools for operations with the tag **products** and HTTP operations of types `POST`, `HEAD`, and `QUERY`.
+
+```yaml
+overlay: 1.0.0
+info:
+ title: Add MCP scopes
+ version: 0.0.0
+actions:
+ - target: $.paths.*["post","head","query"]
+ update: { "x-speakeasy-mcp": { "scopes": ["products"] } }
+```
+
+## Choosing between FastMCP and Speakeasy
+
+FastMCP and Speakeasy are two solid options for building an MCP server. Both can help you ship quickly, but they serve different needs depending on how much control, visibility, and long-term structure you require.
+
+### Visibility
+
+Speakeasy generates explicit code for the server and tools in the `mcp-server` directory. You can inspect how each tool is defined, see the input/output mappings, and modify behavior as needed. This helps when you want to understand or extend how the MCP layer works.
+
+By comparison, you don't see how tools are constructed when using FastMCP. FastMCP automatically converts your FastAPI routes into MCP tools, but the internal logic, prompt structure, and resource handling are hidden. This makes debugging harder as your server grows.
+
+### Setup
+
+Speakeasy requires an OpenAPI document and a short CLI flow to generate the server. While the setup takes a bit more time upfront, it gives you a clean, extensible SDK with a built-in MCP server, ready to integrate with Claude, Cursor, or run as a standalone service.
+
+An advantage of using FastMCP with FastAPI is that you can quickly get a working MCP server. FastMCP reuses your existing FastAPI app, requiring minimal configuration. If your routes are typed and documented, FastMCP can expose them as tools with almost no extra work.
+
+### Customization
+
+With Speakeasy, customization begins in the OpenAPI document. You can change tool names, disable endpoints, apply scopes, or define overlays for external configuration. This makes it easier to create a curated toolset without touching application code.
+
+You have limited customization in FastMCP. You can rename tools, set timeouts, or exclude routes using configuration options, but beyond that, you're constrained by what the abstraction allows.
+
+### Maintainability
+
+Speakeasy separates your server from your application logic. The OpenAPI document becomes the source of truth, and the MCP server is generated from that document.
+
+With FastMCP, your MCP is very close to your FastAPI app. The MCP server depends directly on your controller structure, so changes to endpoints will be reflected in the tools. This tight coupling works in smaller projects, but it can introduce friction as the system evolves.
+
+### Distribution
+
+With Speakeasy, you can publish the MCP server as an npm package or use it directly with `npx`. This allows you to distribute tools across environments or share access with other teams and your users.
+
+You would typically run FastMCP locally inside the Claude desktop app. FastMCP works well for local tools, but it's not built for external packaging or reuse across environments.
+
+## Final thoughts
+
+This guide explored how to build an MCP server for a FastAPI API using FastMCP and Speakeasy. Each tool has its trade-offs, but to summarize:
+
+- Choose FastMCP if you don't have an OpenAPI document or don't plan to deploy and maintain the MCP server in the long term. FastMCP is a quick way to turn your existing controllers into tools, and it handles the complexity for you. It's especially useful if you're just exploring the MCP ecosystem or want to get something running quickly.
+- Choose Speakeasy if you already have an OpenAPI document, plan to maintain the server over time, or want to share it with others. While it requires more initial setup, it gives you more control, visibility, and customization. Speakeasy also works well for prototyping, especially when you want to build something fast while keeping a path open to production.