FastAPI-MCP turns existing FastAPI operations into tools an MCP client can call. It fits an API you already own, such as an order-status endpoint. For a few new Python tools without an existing API, the MCP SDK or FastMCP may be simpler. This guide uses Tadata's fastapi-mcp package.
The example exposes a query while excluding an administrative operation, then calls both a valid order and a missing order through Codex.
Use a separate, compatible environment
With uv, Python 3.12 and Codex CLI available, open PowerShell in an empty project:
uv venv --python 3.12 .venv
uv pip install --python .venv\Scripts\python.exe fastapi-mcp==0.4.0 mcp==1.30.0 uvicorn==0.54.0
SDK 1.30.0 is the compatible combination used here. Keep it separate from projects using SDK 2.
Save the complete application as app.py:
from fastapi import FastAPI, HTTPException
from fastapi_mcp import FastApiMCP
app = FastAPI()
@app.get('/orders/{order_id}', operation_id='read_order')
def read_order(order_id: int):
"""Read a sample order status without modifying it."""
if order_id != 1:
raise HTTPException(status_code=404, detail='Order not found')
return {'order_id':1, 'status':'processing', 'total_cents':20000}
@app.post('/internal/reset', operation_id='internal_reset')
def internal_reset():
"""Placeholder administrative operation excluded from MCP."""
return {'status':'not implemented'}
mcp = FastApiMCP(app, include_operations=['read_order'])
mcp.mount_http()
The explicit operation_id gives the tool a stable name. include_operations exposes only read_order. Define routes before constructing and mounting MCP.
Start the server and leave this terminal running:
.venv\Scripts\python.exe -m uvicorn app:app --host 127.0.0.1 --port 8000
Connect Codex and Claude Code
Open another PowerShell window in the same project:
codex mcp add fastapi --url http://127.0.0.1:8000/mcp
codex mcp list
Start a fresh Codex conversation to call read_order.
For Claude Code:
claude mcp add fastapi --scope project --transport http http://127.0.0.1:8000/mcp
claude mcp list
The health check should show Connected. Cursor's MCP guide documents URL entries; use the same /mcp HTTP endpoint.
Three useful checks
Retrieve an order's status
Use only fastapi MCP. Call read_order with order_id=1 and report the actual
order_id, status and total_cents. Do not infer the status yourself.
The response contains order 1, processing and total_cents: 20000. The amount is in cents; retain the unit when presenting it.
Distinguish a missing order from a broken connection
Call read_order with order_id=999. Preserve the returned error and status
code. Explain whether this is missing data or a server connection failure.
Our tool response contained Status code: 404 and Order not found. That is the API's missing-order path, rather than an inability to connect.
Inspect exposure without calling an administrator tool
List the tools exposed by fastapi MCP. Check that only read_order is present
and internal_reset is absent. Do not call administrative operations.
Expect only read_order. The allowlist controls MCP exposure; the original REST route still exists in FastAPI. API access control remains a separate responsibility.
Troubleshooting
Server.init receives an unexpected argument
An earlier environment resolved MCP SDK 2.3.0, which was incompatible with this FastAPI-MCP 0.4.0 path. Pin mcp==1.30.0 in a separate environment and inspect actual versions with uv pip freeze --python .venv\Scripts\python.exe.
The client cannot connect or uses the wrong transport
This application uses mount_http() and an HTTP client entry. Do not mix it with an older mount()/SSE example. Check that Uvicorn is still running and the URL includes /mcp. If port 8000 is busy, change both the server port and client URLs.
A REST route exists but no tool appears
Check the explicit operation ID against include_operations, and define routes before constructing MCP. Restart this small application and reconnect the client after changes so you inspect the current tool list.
Approval policy rejects the call
Our earlier session returned MCP tool call requires approval, but approval policy is never for read_order. A healthy connection does not mean a particular client session permits every call. Check client permissions; removing API authorization would address a different problem.
Cost, limits and alternatives
The MIT-licensed adapter has no separate local usage charge. Model, API and hosting costs are separate. This unauthenticated loopback example teaches exposure and error behavior; it is not a production authentication design. An MCP allowlist does not secure the remaining REST endpoints.
For existing FastAPI routes, this adapter is an option. To design Python MCP tools directly, see FastMCP or the MCP Python SDK. FastMCP also integrates with FastAPI: check which package and API a guide uses before copying its code.
FAQ
Is FastAPI-MCP the same as FastMCP?
No. This recipe installs fastapi-mcp and imports fastapi_mcp.FastApiMCP. FastMCP is another project with its own integration API. Choose according to whether you are adapting existing routes or building a separate MCP application.
Can I expose only some operations?
Yes: include their operation IDs in include_operations. Our administrator operation was absent from MCP discovery while its REST route remained part of the application. API authorization still matters.
Does a 404 mean MCP is broken?
Inspect where it came from. Order 999 returns the API's missing-data error through a functioning MCP connection. An unavailable Uvicorn process produces a different connection problem.
Can I deploy this example unchanged?
It has no authentication and binds to loopback for local practice. Production use needs separate checks of authorization, exposed operations, error handling and network access; changing the bind address alone is insufficient.
Sources and test scope
Tadata source, package, Claude Code MCP, Codex MCP. Checked 2026-11-16.
Windows, Python 3.12, FastAPI-MCP 0.4.0, SDK 1.30.0, Uvicorn 0.54.0 and Codex CLI 0.169.0. Codex called the real loopback HTTP server: order 1 returned processing/20000 cents; order 999 returned 404. The administrative tool was absent. Claude Code add/list showed Connected. Cursor, production authentication, remote deployment, write APIs and load were not tested.