FastAPI MCP Server: Turn Your FastAPI App into MCP Tools

FastAPI already describes your API in an OpenAPI document, so you're most of the way to an MCP server that Claude and other AI agents can use. What's left is deciding what an agent may do, and writing your routes so a model can tell them apart. This guide takes a small orders API built with FastAPI, turns it into a FastAPI MCP server with MCPcast, the OpenAPI-to-MCP generator in Promptise Foundry, and fixes what a typical day-one app gets wrong. Each fix is proven with the plan MCPcast writes, before and after. At the end, a real agent uses the generated server against the running app. Every command was run against Promptise Foundry 1.3.1, FastAPI 0.143.0 and uvicorn 0.54.0, with gpt-5-mini for the agent and the evaluation, and the output is what it printed.

Start your app, then point MCPcast at the OpenAPI document FastAPI serves at /openapi.json:

pip install promptise
promptise mcpcast http://127.0.0.1:8370/openapi.json --no-curate --profile standard --auth env-token

Parsed 4 operations from http://127.0.0.1:8370/openapi.json; profile=standard 
auth=env-token
╭────────────────────────────────── mcpcast ───────────────────────────────────╮
│ orders → orders-mcp/                                                         │
│   tools: 3  (1 require human approval)                                       │
│   not exposed: 1 operations (with reasons in the plan)                       │
│   files: orders_mcp/ (8 modules), tests/ (2), mcpcast.plan.yaml, server.py,  │
│ README.md, pyproject.toml, Dockerfile, .env.example, .gitignore              │
╰──────────────────────────────────────────────────────────────────────────────╯

MCPcast reads the spec, sorts every operation into read, write, destructive or financial, keeps what the safety profile allows, and writes a standalone Python project: the MCP server, its tests, a plan file that records every decision, and setup for Claude Desktop, Claude Code and Cursor. Nothing is mounted inside your app. The generated server is a separate process that calls your API over HTTP, with your API key. How much of your API makes it through, and how well a model uses it, depends on how the app is written. That's what the rest of this guide is about.

An agent never reads your code. It sees tool names, descriptions and parameters, and MCPcast builds all of them from what FastAPI puts in the spec:

examples=[...]

tags=[...]

The HTTP method and the words in the operation id, path and summary decide each operation's risk: GET is a read, DELETE is destructive, and most POST calls are writes. OpenAPI to MCP: Turn Any REST API into an MCP Server explains the rules and the three safety profiles.

• Python 3.10 or newer. This guide ran on 3.12.

• pip install "promptise>=1.3.1" fastapi uvicorn.

• An OpenAI API key in OPENAI_API_KEY, for the agent and the evaluation at the end. Generating the server with --no-curate needs no key and no network beyond your app.

Here's an orders API the way many of us write it on day one: pydantic models, an API key checked in a dependency, and no thought yet for agents.

import os

from fastapi import Depends, FastAPI, Header, HTTPException
from pydantic import BaseModel

API_KEY = os.environ.get("ORDERS_API_KEY", "dev-key")

app = FastAPI(title="Orders API", version="1.0.0")


def check_key(x_api_key: str = Header()):
    if x_api_key != API_KEY:
        raise HTTPException(status_code=401, detail="invalid API key")


class Item(BaseModel):
    sku: str
    quantity: int


class OrderIn(BaseModel):
    customer: str
    items: list[Item]


class Order(OrderIn):
    id: int
    status: str


ORDERS = {
    1001: Order(id=1001, customer="acme", items=[Item(sku="MUG-01", quantity=2)], status="shipped"),
    1002: Order(id=1002, customer="globex", items=[Item(sku="TEE-M", quantity=1)], status="pending"),
    1003: Order(id=1003, customer="acme", items=[Item(sku="CAP-02", quantity=3)], status="pending"),
}


@app.get("/health")
def health():
    return {"status": "ok"}


@app.get("/orders", dependencies=[Depends(check_key)])
def list_orders(status: str | None = None, limit: int = 20) -> list[Order]:
    found = [o for o in ORDERS.values() if status is None or o.status == status]
    return found[:limit]


@app.get("/orders/{order_id}", dependencies=[Depends(check_key)])
def get_order(order_id: int) -> Order:
    if order_id not in ORDERS:
        raise HTTPException(status_code=404, detail="order not found")
    return ORDERS[order_id]


@app.post("/orders", status_code=201, dependencies=[Depends(check_key)])
def create_order(order: OrderIn) -> Order:
    new = Order(id=max(ORDERS) + 1, status="pending", **order.model_dump())
    ORDERS[new.id] = new
    return new


@app.delete("/orders/{order_id}", status_code=204, dependencies=[Depends(check_key)])
def delete_order(order_id: int):
    if ORDERS.pop(order_id, None) is None:
        raise HTTPException(status_code=404, detail="order not found")

Run it, and check that the spec is there:

uvicorn app:app --port 8370 --reload
curl -s http://127.0.0.1:8370/openapi.json | head -c 200

{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"paths":{"/health":{"get":{"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Respons

--reload restarts the app every time you save, which you'll want in the next steps.

Generate a first server. --no-curate keeps every decision in MCPcast's own rules, offline, so you can repeat this run and get the same result:

promptise mcpcast http://127.0.0.1:8370/openapi.json --no-curate

Parsed 5 operations from http://127.0.0.1:8370/openapi.json; profile=read-only 
auth=passthrough
╭────────────────────────────────── mcpcast ───────────────────────────────────╮
│ orders → orders-mcp/                                                         │
│   tools: 1  (0 require human approval)                                       │
│   not exposed: 4 operations (with reasons in the plan)                       │
│   files: orders_mcp/ (8 modules), tests/ (2), mcpcast.plan.yaml, server.py,  │
│ README.md, pyproject.toml, Dockerfile, .env.example, .gitignore              │
╰──────────────────────────────────────────────────────────────────────────────╯

One tool out of five operations, and it's the health check. Open orders-mcp/mcpcast.plan.yaml to see why:

tools:
- name: health_health_get
  description: Health
  risk: read
  routes:
  - operation_id: health_health_get
    method: GET
    path: /health
dropped:
- operation_id: list_orders_orders_get
  reason: 'unsupported by mcpcast: required header parameter ''x-api-key'' cannot be sent'
- operation_id: create_order_orders_post
  reason: 'unsupported by mcpcast: required header parameter ''x-api-key'' cannot be sent'
- operation_id: get_order_orders_order_id_get
  reason: 'unsupported by mcpcast: required header parameter ''x-api-key'' cannot be sent'
- operation_id: delete_order_orders_order_id_delete
  reason: 'unsupported by mcpcast: required header parameter ''x-api-key'' cannot be sent'

x_api_key: str = Header() reads like authentication to you, but in the spec it's just a required header parameter, the same as any other. The generated server doesn't send header parameters, and the only credential it sends is the one your spec's security scheme describes. An operation that needs any other header could never succeed, so MCPcast drops it with the reason, instead of generating a tool that fails on every call. Notice the write and the delete were dropped for the header too, before the default read-only profile even got a say.

FastAPI's APIKeyHeader checks the same header, and also tells the spec that it's a credential. It's a small change to the dependency:

from fastapi import Depends, FastAPI, HTTPException, Security
from fastapi.security import APIKeyHeader
api_key_header = APIKeyHeader(name="X-API-Key")


def check_key(key: str = Security(api_key_header)):
    if key != API_KEY:
        raise HTTPException(status_code=401, detail="invalid API key")

Save, and run the same command again:

Parsed 5 operations from http://127.0.0.1:8370/openapi.json; profile=read-only 
auth=passthrough
Error: the spec authenticates with a credential in header 'X-API-Key', which --auth passthrough cannot relay (it forwards only the caller's Authorization header) — generate with --auth env-token (one upstream credential from MCPCAST_UPSTREAM_TOKEN, presented there) or --auth api-key (one per tenant)

Progress. MCPcast now knows where the key goes, and it's telling you the default auth mode can't put it there. The auth mode decides where the generated server gets the credential it sends to your app:

• passthrough (the default) forwards each caller's own Authorization header. It's for shared HTTP deployments where every user brings a token, and it can't fill an X-API-Key header.

• env-token sends one credential from the MCPCAST_UPSTREAM_TOKEN environment variable, in the header your spec names. This is the one for your own agent, Claude Desktop or Claude Code.

• api-key gives each customer their own key to the MCP server, with your API credential per customer kept on the server.

Use env-token. --force lets MCPcast overwrite the project from step 2:

promptise mcpcast http://127.0.0.1:8370/openapi.json --no-curate --auth env-token --force

Parsed 5 operations from http://127.0.0.1:8370/openapi.json; profile=read-only 
auth=env-token
╭────────────────────────────────── mcpcast ───────────────────────────────────╮
│ orders → orders-mcp/                                                         │
│   tools: 3  (0 require human approval)                                       │
│   not exposed: 2 operations (with reasons in the plan)                       │
│   files: orders_mcp/ (9 modules), tests/ (2), mcpcast.plan.yaml, server.py,  │
│ README.md                                                                    │
╰──────────────────────────────────────────────────────────────────────────────╯

Three tools now. Here's the plan before and after, trimmed with …:

@@ -5,9 +5,10 @@
 api:
   name: orders
   base_url: http://127.0.0.1:8370
-  auth: passthrough
+  auth: env-token
   description: Orders API
   spec_source: http://127.0.0.1:8370/openapi.json
+  credential_name: X-API-Key
…
+- name: list_orders_orders_get
+  description: List Orders
…
+- name: get_order_orders_order_id_get
+  description: Get Order
…
 dropped:
-- operation_id: list_orders_orders_get
-  reason: 'unsupported by mcpcast: required header parameter ''x-api-key'' cannot be sent'
 - operation_id: create_order_orders_post
-  reason: 'unsupported by mcpcast: required header parameter ''x-api-key'' cannot be sent'
-- operation_id: get_order_orders_order_id_get
-  reason: 'unsupported by mcpcast: required header parameter ''x-api-key'' cannot be sent'
+  reason: write operation excluded by profile 'read-only'
 - operation_id: delete_order_orders_order_id_delete
-  reason: 'unsupported by mcpcast: required header parameter ''x-api-key'' cannot be sent'
+  reason: destructive operation excluded by profile 'read-only'

The two reads are tools. The write and the delete are now out for the right reason: the safety profile, which you'll change in step 6.

Every FastAPI auth style ends up in one of three places. Planning a one-route app with each style in MCPcast 1.3.1 gave this:

The tool names are still list_orders_orders_get and get_order_orders_order_id_get. FastAPI builds each operation id from the function name, the path and the method, and MCPcast uses the operation id as the tool name. A model picking between names like that is guessing. Fix it once, on the app:

app = FastAPI(
    title="Orders API",
    version="1.0.0",
    # Name each operation after its function: list_orders, not list_orders_orders_get.
    generate_unique_id_function=lambda route: route.name,
)

Your function names must then be unique across the app. Setting operation_id="..." on a single route works too. Run the same command again, and the plan changes like this:

 tools:
-- name: health_health_get
+- name: health
   description: Health
   risk: read
   routes:
-  - operation_id: health_health_get
+  - operation_id: health
     method: GET
     path: /health
-- name: list_orders_orders_get
+- name: list_orders
   description: List Orders
   risk: read
   routes:
-  - operation_id: list_orders_orders_get
+  - operation_id: list_orders
…
-- name: get_order_orders_order_id_get
+- name: get_order
   description: Get Order
…
 dropped:
-- operation_id: create_order_orders_post
+- operation_id: create_order
   reason: write operation excluded by profile 'read-only'
-- operation_id: delete_order_orders_order_id_delete
+- operation_id: delete_order
   reason: destructive operation excluded by profile 'read-only'

Fix names in your app rather than in the plan. You can rename tools in mcpcast.plan.yaml, but the next run from the spec brings the derived names back.

List Orders and Get Order are what FastAPI makes of the function names. The model reads nothing else when it picks a tool, so tell it what each operation does and when to use it. Here are the routes with a summary, a docstring, a tag, and a description and example on every parameter:

Status = Literal["pending", "shipped"]
OrderId = Annotated[int, Path(description="The order number, for example 1001.", examples=[1001])]


class Item(BaseModel):
    sku: str = Field(description="Product code, for example MUG-01.", examples=["MUG-01"])
    quantity: int = Field(ge=1, le=100, description="How many units to order.", examples=[2])


class OrderIn(BaseModel):
    customer: str = Field(description="Customer account name, for example acme.", examples=["acme"])
    items: list[Item] = Field(min_length=1, description="The products and quantities to order.")


@app.get("/health", include_in_schema=False)
def health():
    return {"status": "ok"}


@app.get("/orders", tags=["orders"], summary="List orders", dependencies=[Depends(check_key)])
def list_orders(
    status: Annotated[Status | None, Query(description="Only orders with this status: pending or shipped.")] = None,
    limit: Annotated[int, Query(ge=1, le=100, description="Maximum number of orders to return.")] = 20,
) -> list[Order]:
    """Newest orders first. Use get_order when you already know the order number."""

include_in_schema=False takes the health check out of the spec. A load balancer needs it; an agent has no task that does. The complete file is at the end of this section. Run the same command again:

-- name: health
-  description: Health
-  risk: read
-  routes:
-  - operation_id: health
-    method: GET
-    path: /health
 - name: list_orders
-  description: List Orders
+  description: List orders. Newest orders first. Use get_order when you already know the order number.
   risk: read
…
   params:
     status:
+      description: 'Only orders with this status: pending or shipped.'
…
     limit:
+      description: Maximum number of orders to return.
…
+  tags:
+  - orders
 - name: get_order
-  description: Get Order
+  description: Get one order. Returns the customer, items and status of a single order.
…
     order_id:
+      description: The order number, for example 1001.
…
   example:
-    order_id: 1
+    order_id: 1001
+  tags:
+  - orders

The summary and docstring became one description. Every parameter has its own description now. The example for get_order uses an order that exists, instead of 1, which doesn't. The orders tag is kept on each tool and names the module it's generated in, orders_mcp/tools/orders.py.

That's what the agent will see, written into the generated server:

    @server.tool(
        name="list_orders",
        description=(
            "List orders. Newest orders first. Use get_order when you already know the order "
            "number.\n"
            "\n"
            "Parameters:\n"
            "  - status (string): Only orders with this status: pending or shipped.; one of: "
            "pending, shipped\n"
            "  - limit (integer): Maximum number of orders to return.; default 20"
        ),
        tags=["orders"],
        read_only_hint=True,
        idempotent_hint=True,
        open_world_hint=True,
    )
    @advertise(PARAM_SCHEMAS["list_orders"])

@advertise puts each parameter's JSON Schema from the plan into the tool's input schema, so the allowed values and limits reach the agent too. This is the list_orders schema the agent receives:

{'status': {'anyOf': [{'enum': ['pending', 'shipped'], 'type': 'string'}, {'type': 'null'}], 'description': 'Only orders with this status: pending or shipped.', 'title': 'Status'}, 'limit': {'default': 20, 'description': 'Maximum number of orders to return.', 'maximum': 100, 'minimum': 1, 'title': 'Limit', 'type': 'integer'}}

The Literal values became an enum, and ge=1, le=100 became minimum and maximum. Your FastAPI app still enforces them on every call; the schema tells the model about them before it calls. A Promptise agent passes them on to its model since Promptise 1.3.1.

Agents that only read are useful, but the sales team also wants to place orders. The standard profile generates writes and puts every one of them behind human approval. --review -y prints the plan as a table before writing it:

promptise mcpcast http://127.0.0.1:8370/openapi.json --no-curate --profile standard --auth env-token --review -y --force

Parsed 4 operations from http://127.0.0.1:8370/openapi.json; profile=standard auth=env-token
                                    Tools (3) — profile standard                                    
┏━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Tool         ┃ Risk  ┃ Approval ┃ Operations           ┃ Params          ┃ Description           ┃
┡━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━┩
│ list_orders  │ read  │ —        │ GET /orders          │ status, limit   │ List orders. Newest   │
…
│ create_order │ write │ required │ POST /orders         │ customer, items │ Create an order.      │
…
│ get_order    │ read  │ —        │ GET                  │ order_id        │ Get one order.        │
…
└──────────────┴───────┴──────────┴──────────────────────┴─────────────────┴───────────────────────┘
                            Not exposed (1)                            
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Operation    ┃ Reason                                               ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ delete_order │ destructive operation excluded by profile 'standard' │
└──────────────┴──────────────────────────────────────────────────────┘
╭─────────────────────────────────────── mcpcast ───────────────────────────────────────╮
│ orders → orders-mcp/                                                                  │
│   tools: 3  (1 require human approval)                                                │
│   not exposed: 1 operations (with reasons in the plan)                                │
│   files: orders_mcp/ (8 modules), tests/ (2), mcpcast.plan.yaml, server.py, README.md │
╰───────────────────────────────────────────────────────────────────────────────────────╯

create_order is a write with requires_approval: true in the plan. Its example came straight from your Field examples:

  example:
    customer: acme
    items:
    - sku: MUG-01
      quantity: 2
  requires_approval: true

delete_order stays out: standard never generates destructive operations. With --profile full it becomes a fourth tool, delete_order, risk destructive, also behind approval. Leave deletes to people unless you have a reason.

The project is an ordinary Python package with its own tests. They run against a fake of your API, so they never touch real orders:

cd orders-mcp
pip install -e ".[dev]"
pytest -q

......                                                                   [100%]
6 passed in 0.05s

The six tests check that every tool is listed, that every parameter advertises its schema from the plan, that each tool calls the right method and route, and that a denied create_order never reaches your API.

Here's a Promptise agent connected to the generated server, the same pattern as in How to Connect MCP Servers to Your AI Agent in Python. MCPCAST_UPSTREAM_TOKEN holds your API key. Because your spec names the X-API-Key header, the value is the raw key, with no Bearer in front:

import asyncio
import sys

from promptise import build_agent
from promptise.config import StdioServerSpec


async def main():
    agent = await build_agent(
        model="openai:gpt-5-mini",
        servers={
            "orders": StdioServerSpec(
                command=sys.executable,
                args=["orders-mcp/server.py"],
                env={"MCPCAST_UPSTREAM_TOKEN": "dev-key"},
            ),
        },
        instructions=(
            "You help the sales team with customer orders. Use your tools. "
            "If a tool call is denied, say so plainly and do not retry it."
        ),
        trace_tools=True,
    )
    try:
        for question in [
            "Which orders are still pending, and what is in them?",
            "Create an order for globex: 3 of MUG-01.",
        ]:
            result = await agent.ainvoke({"messages": [{"role": "user", "content": question}]})
            print(">>>", result["messages"][-1].content)
    finally:
        await agent.shutdown()


asyncio.run(main())

Run it with your app still up:

→ Invoking tool: list_orders with {'status': 'pending', 'limit': 20}
✔ Tool result from list_orders: [{"customer": "acme", "items": [{"sku": "CAP-02", "quantity": 3}], "id": 1003, "status": "pending"}, {"customer": "globex", "items": [{"sku": "TEE-M", "quantity": 1}], "id": 1002, "status": "pending"}]
>>> There are two pending orders:

- Order 1003 (customer: acme) — 3 × CAP-02
- Order 1002 (customer: globex) — 1 × TEE-M
→ Invoking tool: create_order with {'customer': 'globex', 'items': [{'sku': 'MUG-01', 'quantity': 3}]}
Elicitation request failed (McpError: Elicitation not supported) — treated as declined
✖ create_order error: APPROVAL_DENIED: Approval denied for tool 'create_order': client declined or returned an invalid elicitation response
>>> I’m sorry — I couldn’t create the order. The create_order tool call was denied (approval denied), so I don’t have permission to place the order right now.

I can help in one of these ways — tell me which you want:
- Retry creating the order once tool permission is available.
- I can prepare the exact order payload for you to paste/run yourself:
  {"customer":"globex","items":[{"sku":"MUG-01","quantity":3}]}
- Review/check SKUs or list current orders instead.

Please confirm how you’d like to proceed.

The read went straight to your live app, with the status filter the description advertised. The write was stopped before it reached your app, and the order list afterwards still has the same three orders. The line right after the create_order call is the generated server's own log message, and it says why: approval in this server uses MCP elicitation, where the server asks the client to confirm the exact call. This agent was built without an approval handler, so it tells the server it can't answer, and the server fails closed. OpenAPI to MCP: Turn Any REST API into an MCP Server shows a handler that sees the server's question, and the pending approval mode for agents that run without a person at the client.

To see the approved path, give the agent a reviewer. With approval=, build_agent sends the server's confirmation request to your handler and answers with its decision. This version of agent.py approves the write after printing what the server asks:

import asyncio
import sys

from promptise import build_agent
from promptise.approval import ApprovalDecision, ApprovalRequest
from promptise.config import StdioServerSpec


async def reviewer(request: ApprovalRequest) -> ApprovalDecision:
    """Stands in for a person: show what the server asks, then say yes."""
    print(request.context_summary)
    return ApprovalDecision(approved=True)


async def main():
    agent = await build_agent(
        model="openai:gpt-5-mini",
        servers={
            "orders": StdioServerSpec(
                command=sys.executable,
                args=["orders-mcp/server.py"],
                env={"MCPCAST_UPSTREAM_TOKEN": "dev-key"},
            ),
        },
        instructions=(
            "You help the sales team with customer orders. Use your tools. "
            "If a tool call is denied, say so plainly and do not retry it."
        ),
        approval=reviewer,
        trace_tools=True,
    )
    try:
        result = await agent.ainvoke(
            {"messages": [{"role": "user", "content": "Create an order for globex: 3 of MUG-01."}]}
        )
        print(">>>", result["messages"][-1].content)
    finally:
        await agent.shutdown()


asyncio.run(main())

→ Invoking tool: create_order with {'customer': 'globex', 'items': [{'sku': 'MUG-01', 'quantity': 3}]}
Server 'orders' asks: Approval required: call tool 'create_order' with arguments {'customer': 'globex', 'items': [{'sku': 'MUG-01', 'quantity': 3}]}. Approve?
✔ Tool result from create_order: {"customer": "globex", "items": [{"sku": "MUG-01", "quantity": 3}], "id": 1004, "status": "pending"}
>>> Order created — #1004
Customer: globex
Items:
- MUG-01 × 3
Status: pending

Would you like me to do anything else with this order?

The reviewer saw the exact call, said yes, and order 1004 now exists in your app, whose log shows the one POST /orders of this whole guide. In production the handler asks a person, for example through a webhook or a queue: Server-side approval gates lists the handlers approval= accepts. For tests, build_server(approval_handler=...) in the generated package takes a reviewer function too, and TestClient runs the whole server in memory, gate included.

For Claude, the generated orders-mcp/README.md has the setup filled in for your server. For Claude Desktop, add this to claude_desktop_config.json, with the absolute path to server.py and your key:

{
  "mcpServers": {
    "orders": { "command": "python", "args": ["/absolute/path/to/server.py"], "env": {"MCPCAST_UPSTREAM_TOKEN": "<your API key>"} }
  }
}

For Claude Code, it's one command:

claude mcp add orders -e MCPCAST_UPSTREAM_TOKEN="<your API key>" -- python /absolute/path/to/server.py

Use a python that has promptise installed. The key goes in the client's config, because a desktop app started from the dock doesn't see variables you export in a terminal.

The finished app

Here's app.py after all four fixes:

import os
from typing import Annotated, Literal

from fastapi import Depends, FastAPI, HTTPException, Path, Query, Security
from fastapi.security import APIKeyHeader
from pydantic import BaseModel, Field

API_KEY = os.environ.get("ORDERS_API_KEY", "dev-key")

app = FastAPI(
    title="Orders API",
    version="1.0.0",
    # Name each operation after its function: list_orders, not list_orders_orders_get.
    generate_unique_id_function=lambda route: route.name,
)

api_key_header = APIKeyHeader(name="X-API-Key")


def check_key(key: str = Security(api_key_header)):
    if key != API_KEY:
        raise HTTPException(status_code=401, detail="invalid API key")


Status = Literal["pending", "shipped"]
OrderId = Annotated[int, Path(description="The order number, for example 1001.", examples=[1001])]


class Item(BaseModel):
    sku: str = Field(description="Product code, for example MUG-01.", examples=["MUG-01"])
    quantity: int = Field(ge=1, le=100, description="How many units to order.", examples=[2])


class OrderIn(BaseModel):
    customer: str = Field(description="Customer account name, for example acme.", examples=["acme"])
    items: list[Item] = Field(min_length=1, description="The products and quantities to order.")


class Order(OrderIn):
    id: int
    status: Status


ORDERS = {
    1001: Order(id=1001, customer="acme", items=[Item(sku="MUG-01", quantity=2)], status="shipped"),
    1002: Order(id=1002, customer="globex", items=[Item(sku="TEE-M", quantity=1)], status="pending"),
    1003: Order(id=1003, customer="acme", items=[Item(sku="CAP-02", quantity=3)], status="pending"),
}


@app.get("/health", include_in_schema=False)
def health():
    return {"status": "ok"}


@app.get("/orders", tags=["orders"], summary="List orders", dependencies=[Depends(check_key)])
def list_orders(
    status: Annotated[Status | None, Query(description="Only orders with this status: pending or shipped.")] = None,
    limit: Annotated[int, Query(ge=1, le=100, description="Maximum number of orders to return.")] = 20,
) -> list[Order]:
    """Newest orders first. Use get_order when you already know the order number."""
    found = [o for o in ORDERS.values() if status is None or o.status == status]
    return sorted(found, key=lambda o: o.id, reverse=True)[:limit]


@app.get("/orders/{order_id}", tags=["orders"], summary="Get one order", dependencies=[Depends(check_key)])
def get_order(order_id: OrderId) -> Order:
    """Returns the customer, items and status of a single order."""
    if order_id not in ORDERS:
        raise HTTPException(status_code=404, detail="order not found")
    return ORDERS[order_id]


@app.post("/orders", status_code=201, tags=["orders"], summary="Create an order", dependencies=[Depends(check_key)])
def create_order(order: OrderIn) -> Order:
    """Places a new order in status pending. Check the SKUs with the customer first."""
    new = Order(id=max(ORDERS) + 1, status="pending", **order.model_dump())
    ORDERS[new.id] = new
    return new


@app.delete("/orders/{order_id}", status_code=204, tags=["orders"], summary="Delete an order", dependencies=[Depends(check_key)])
def delete_order(order_id: OrderId):
    """Removes an order for good. There is no undo."""
    if ORDERS.pop(order_id, None) is None:
        raise HTTPException(status_code=404, detail="order not found")

Good names and descriptions are a judgement call until you measure them. --eval has a model write realistic tasks for your tools, then a real agent tries each one against the generated server. Reads go to your live app; writes go to mocks built from the spec, so nothing changes. Run it on the plan:

export OPENAI_API_KEY="sk-..."
export MCPCAST_UPSTREAM_TOKEN=dev-key
promptise mcpcast orders-mcp/mcpcast.plan.yaml --eval --eval-tasks 8

Regenerating from plan orders-mcp/mcpcast.plan.yaml (3 tools)
…
Evaluating with openai:gpt-5-mini (8 tasks)…
Agent Readiness: A  (8/8 tasks succeeded)
  • `list_orders` has no example — agents lean on examples heavily
…

The report in orders-mcp/eval/report.md gives a score of 1.00, the right tool chosen first in all 8 tasks, and no parameter errors. Your app's log shows every read the agent made:

INFO:     127.0.0.1:50406 - "GET /orders?status=pending&limit=2 HTTP/1.1" 200 OK
INFO:     127.0.0.1:50406 - "GET /orders HTTP/1.1" 200 OK
INFO:     127.0.0.1:50450 - "GET /orders/1001 HTTP/1.1" 200 OK
INFO:     127.0.0.1:50450 - "GET /orders/1001 HTTP/1.1" 200 OK
INFO:     127.0.0.1:50450 - "GET /orders/1001 HTTP/1.1" 200 OK

The get_order tasks all asked for order 1001, the number in the plan's example, so nothing came back not found. The three create_order tasks went to mocks, which is why the log has no POST. The one suggestion is fair: list_orders has no required parameters, so it gets no generated example, and you can add one in mcpcast.plan.yaml. Scores move between runs, too: an earlier run of this evaluation, on an older Promptise version, scored 7 of 8, because the task writer made up an order number that doesn't exist. If you use --eval as a release check, set a floor rather than expecting a number.

When the API doesn't recognise an identifier, the report says whether it came from the plan's example, from the agent guessing, or from the task or a mocked reply, and only the first two ask you to change the plan. It has done so since Promptise Foundry 1.3.0.

• Required header and cookie parameters drop the operation. That includes tenant headers like X-Tenant. Optional ones are left off the tool. Move credentials into a security scheme, and anything else into the path, query or body.

• Allowed values and limits are advertised, not enforced, by the generated server. The tool schema shows them to the agent; the generated handler checks only base types, and your app checks the rest.

• A Promptise agent needs an approval handler for writes. Without approval= on build_agent, the agent tells the server it can't confirm calls, so gated tools are denied. Pass a handler as in step 8, or use --auth api-key with pending approvals, covered in Human approval.

• Only required, nullable body fields can be sent as null. A required JSON body property your spec marks as nullable accepts None and is sent as null. An optional parameter's None is left out of the request, so a PATCH that clears an optional field by sending null won't work through a generated tool.

• The base URL is baked in. The plan records where your app was when you generated it, here http://127.0.0.1:8370. Set MCPCAST_BASE_URL to point the same server at staging or production.

• An env-token server is for one person. Over HTTP it binds loopback only, since anyone reaching it would act with your key. For a shared deployment, regenerate with --auth api-key or passthrough.

The full list is in the limits section of the MCPcast reference.

How is MCPcast different from fastapi-mcp?

fastapi-mcp is an open-source library from Tadata that exposes your FastAPI endpoints as MCP tools, and can mount the MCP server directly inside your app. MCPcast takes a different route: it works from the OpenAPI document, so it isn't tied to FastAPI, and it generates a separate, editable server project. Before writing any code it classifies every operation's risk, applies a safety profile, gates writes behind human approval in the server, and records every decision with its reason in a plan file you review. --eval then measures how well a real agent uses the result.

Can Claude Desktop or Claude Code use my FastAPI MCP server?

Yes. The generated server speaks MCP over stdio, which is what both clients start, and the generated README has the exact config for Claude Desktop, Claude Code and Cursor. Put your API key in the client's config as MCPCAST_UPSTREAM_TOKEN, as shown in step 8.

How does authentication work for a FastAPI MCP server?

There are two hops. Your MCP client talks to the generated server, and the generated server talks to your FastAPI app with the credential your security scheme describes. The key lives in the server's environment, never in tool arguments, so the model never handles it. For a server many customers share, --auth api-key gives each one their own key to the MCP server.

Do I have to change my FastAPI app?

Not to start, but you'll get a much better server if you do. A security scheme instead of a Header() parameter, real operation ids, and descriptions on routes and fields are the changes this guide made, and none of them changes what your endpoints do. Two things do change at the edges: a request without a key now gets 401 Not authenticated instead of a 422 validation error, and new operation ids rename the methods in any client generated from your spec.

Is there a guided setup?

Yes. Run promptise mcpcast with no arguments for an interactive setup in your terminal. It can detect a FastAPI app running on a usual local port such as 8000, shows every tool for review, and writes nothing until you confirm. See Guided setup.

• Make your Python API MCP-ready: the docs walkthrough for FastAPI, Django, Flask and Litestar, including a CI check that keeps the plan in sync with your app.

• MCPcast reference: every option, the plan format, the auth modes and the readiness score.

• Approval Gates: elicitation, pending approvals and custom handlers.

• MCPcast recipes: what happens on large real-world APIs.

• OpenAPI to MCP: Turn Any REST API into an MCP Server: curation with a model, plan edits and the approval flow in depth.

• How to Connect MCP Servers to Your AI Agent in Python: use your new server from your own agent.