Third-party toolUpdated 2026.11.22

FastAPI-MCP on Windows: Expose Selected API Tools to Codex

Expose selected FastAPI operations to Codex over HTTP on Windows. Includes a compatible SDK pin, complete order API, real 404 behavior and allowlist limitations.

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.

Subscribe to AI tool picks and practical advice

Get worthwhile tool picks, test findings and important updates in your inbox.

Get a monthly-updated list of AI tools and Skills right away. We email when there are worthwhile tool picks, test findings or important updates. Unsubscribe anytime. Privacy

Almost done: check your inboxClick the button in the confirmation email and you will get the download link for the tool list. If you do not see it, check your spam or Promotions folder.

Past issues

Or follow us on: