FastAPI MCP MCP — 사용 사례, 설치 & 라이브 데모

왜 쓰나요

핵심 기능

One-line mount: FastApiMCP(app).mount() — tools appear automatically
Schemas from Pydantic — no duplicate type definitions
FastAPI auth/deps still fire — middleware, Depends, OAuth2 just work
Filter which routes become tools via include/exclude tags

라이브 데모

실제 사용 모습

fastapi-mcp.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fastapi-mcp": {
      "command": "uvx",
      "args": [
        "fastapi-mcp"
      ]
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "fastapi-mcp": {
      "command": "uvx",
      "args": [
        "fastapi-mcp"
      ]
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "fastapi-mcp": {
      "command": "uvx",
      "args": [
        "fastapi-mcp"
      ]
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "fastapi-mcp": {
      "command": "uvx",
      "args": [
        "fastapi-mcp"
      ]
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "fastapi-mcp",
      "command": "uvx",
      "args": [
        "fastapi-mcp"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "fastapi-mcp": {
      "command": {
        "path": "uvx",
        "args": [
          "fastapi-mcp"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add fastapi-mcp -- uvx fastapi-mcp

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: FastAPI MCP

Expose an existing FastAPI app as MCP without refactoring

👤 Backend devs with a running FastAPI service ⏱ ~30 min intermediate

언제 쓸까: You already ship a FastAPI API. You want agents to use it. You don't want a parallel codebase.

사전 조건

Working FastAPI app with Pydantic models on requests/responses — If your routes return dict, refactor to Pydantic BaseModel first — otherwise tool schemas will be object

흐름

Install and mount

Add fastapi-mcp to my project. In my main.py, after app = FastAPI(), add FastApiMCP(app).mount(). Show the diff.✓ 복사됨

→ Minimal diff; server still runs
Verify tools appear

Run the server. Connect with npx -y mcp-remote http://localhost:8000/mcp. List tools — do all my GET/POST routes show up?✓ 복사됨

→ Tools listed, names match route operation_ids
Filter what's exposed

I don't want /admin/* routes exposed. Reconfigure with include_operations or exclude by tag.✓ 복사됨

→ Admin routes no longer in tool list

결과: Your existing API is now MCP-addressable with zero duplication of schemas or logic.

함정

Every route becomes a tool — including internal ones you didn't mean to expose — Explicitly set include_tags=['public'] or exclude_operations=[...] before going live
Routes without operation_id get generated names like read_item_items__item_id__get — ugly — Always set explicit operation_id on routes: @app.get('/items/{id}', operation_id='get_item')

함께 쓰기: fastmcp

Expose an authenticated FastAPI app as MCP without breaking auth

👤 Backend devs with bearer/OAuth2 on FastAPI ⏱ ~30 min intermediate

언제 쓸까: Your FastAPI routes use Depends(get_current_user) — you need that to still fire when called via MCP.

사전 조건

Existing auth dependency — Depends(oauth2_scheme) or equivalent

흐름

Pass through the Authorization header

Configure fastapi-mcp to forward the Authorization header from MCP context to the underlying route. Point me at the settings.✓ 복사됨

→ Config change; routes now receive the header
Test an authed call

Call the protected endpoint via MCP. First with no token (expect 401), then with a valid one (expect 200).✓ 복사됨

→ 401 unauth, 200 auth — same as direct HTTP
Document the client-side setup

Write the mcp-remote config users need so their Claude Desktop passes an Authorization header.✓ 복사됨

→ Copy-pasteable client config snippet

결과: Auth enforced identically whether called from curl or from an agent.

함정

Agent accidentally uses a long-lived root token — Mint short-lived scoped tokens per user; rotate aggressively — treat MCP like any other API client

Deploy the MCP endpoint alongside your existing API

👤 Platform engineers ⏱ ~45 min advanced

언제 쓸까: You run FastAPI on Cloud Run / Fly / Render. You want MCP to share that deploy.

흐름

Mount at a stable path

Mount fastapi-mcp at /mcp. Confirm /docs (Swagger) and /mcp both work from the same process.✓ 복사됨

→ Both paths respond
Expose via your existing ingress

Update my Cloud Run / nginx / API gateway config to route /mcp to this service with SSE-compatible timeouts (no buffering, long idle).✓ 복사됨

→ Remote mcp-remote connects cleanly
Document the client setup

Write the team-facing README: how to add this MCP to Claude Desktop + Cursor.✓ 복사됨

→ Copy-paste config per client

결과: One deploy, two protocols (REST + MCP), zero extra infra.

함정

Proxy buffers SSE responses, connection appears hung — Disable proxy buffering — nginx: proxy_buffering off; Cloud Run: already fine; Cloudflare: enable streaming

함께 쓰기: cloud-run · vercel

조합

다른 MCP와 조합해 10배 효율

fastapi-mcp + fastmcp

Use fastapi-mcp for legacy routes, FastMCP for greenfield agent-specific tools in the same process

Mount fastapi-mcp for my existing /api/* routes and register 3 new FastMCP tools for agent-only operations like bulk_sync.✓ 복사됨

fastapi-mcp + cloud-run

Deploy REST + MCP together on Cloud Run

Take my FastAPI service, add fastapi-mcp, containerize, and deploy to Cloud Run with IAM auth on /mcp.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
FastApiMCP(app, **options)	app: FastAPI, include_operations?, exclude_operations?, include_tags?, exclude_tags?, name?, description?	Build-time wiring — create once at startup	free
.mount(path='/mcp')	path?	Right after instantiation	free
Auto-generated tools	derived from each FastAPI route's request/response models	No action — they appear once you mount	same as your route

비용 및 제한

운영 비용

API 쿼터: Inherits from your API
호출당 토큰: Same as direct HTTP calls — no overhead
금액: Free, open source
팁: Exclude verbose admin/debug routes from MCP — they pollute the agent's tool list and cost tokens on every list_tools

보안

권한, 시크릿, 파급범위

자격 증명 저장: Whatever your FastAPI uses — fastapi-mcp doesn't add a new auth layer

데이터 외부 송신: Wherever your routes already go

Not first-party Anthropic — tadata-org community project. Pin to a specific version and review changes before bumping.

문제 해결

자주 발생하는 오류와 해결

Tools appear but calls return 422 validation errors

Your route uses dict instead of Pydantic BaseModel — MCP passes typed JSON and your route can't parse it. Refactor to BaseModel.

Route exists at /items but no matching tool

fastapi-mcp skips routes without a response_model or operation_id in some cases. Add response_model=ItemOut and operation_id='get_item'.

확인: curl http://localhost:8000/openapi.json | jq '.paths'

Auth dependency doesn't fire when called via MCP

Configure header forwarding in FastApiMCP options. If your dependency reads cookies instead of headers, switch to header-based auth — MCP has no cookie jar.

SSE hangs behind nginx

Add proxy_buffering off; proxy_cache off; proxy_read_timeout 3600s; to the /mcp location block.

대안

FastAPI MCP 다른 것과 비교

대안	언제 쓰나	단점/장점
FastMCP	Greenfield — no existing FastAPI app, just writing an MCP server	Cleaner DX for new projects; fastapi-mcp wins for retrofitting
Hand-written SDK server	You need fine-grained control over tool names, descriptions, and schemas	More code, more maintenance — usually not worth it

FastAPI MCP

왜 쓰나요

핵심 기능

라이브 데모

실제 사용 모습

설치

클라이언트 선택

사용 사례

실전 활용법: FastAPI MCP

Expose an existing FastAPI app as MCP without refactoring

사전 조건

흐름

함정

Expose an authenticated FastAPI app as MCP without breaking auth

사전 조건

흐름

함정

Deploy the MCP endpoint alongside your existing API

흐름

함정

조합

다른 MCP와 조합해 10배 효율

도구

이 MCP가 노출하는 것

비용 및 제한

운영 비용

보안

권한, 시크릿, 파급범위

문제 해결

자주 발생하는 오류와 해결

대안

FastAPI MCP 다른 것과 비교

더 보기

리소스