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

왜 쓰나요

핵심 기능

Single decorator per tool: @mcp.tool or @mcp.resource
Type hints become JSON schemas — no manual schema writing
Async-first, supports sync too — stdlib typing works
Transports built in: stdio (for desktop clients), SSE / streamable HTTP (for remote)

라이브 데모

실제 사용 모습

fastmcp.replay ▶ 준비됨

0/0

설치

클라이언트 선택

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

{
  "mcpServers": {
    "fastmcp": {
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  }
}

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

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

{
  "mcpServers": {
    "fastmcp": {
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  }
}

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

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "fastmcp": {
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  }
}

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

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "fastmcp": {
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  }
}

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

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "fastmcp",
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  ]
}

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

~/.config/zed/settings.json

{
  "context_servers": {
    "fastmcp": {
      "command": {
        "path": "uvx",
        "args": [
          "fastmcp"
        ]
      }
    }
  }
}

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

claude mcp add fastmcp -- uvx fastmcp

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

사용 사례

실전 활용법: FastMCP

Expose an internal REST API as an MCP in under an hour

👤 Backend engineers with an existing Python service ⏱ ~45 min intermediate

언제 쓸까: You have a company API that agents should be able to call, and you don't want to write a client spec from scratch.

사전 조건

Python 3.10+ — python --version
uv installed — curl -LsSf https://astral.sh/uv/install.sh | sh

흐름

Bootstrap the project

Scaffold a FastMCP server project called 'acme-api-mcp' with one starter tool. Use uv for dependency management.✓ 복사됨

→ pyproject.toml + server.py with a working @mcp.tool example
Wrap the 3 highest-value endpoints

My internal API has endpoints /orders/{id}, /customers/search, /invoices/{id}/pdf. Write a FastMCP tool for each, using httpx.AsyncClient and reading AUTH_TOKEN from env.✓ 복사됨

→ 3 decorated functions with type hints + docstrings that become tool descriptions
Test locally with the MCP Inspector

Run the server with uv run mcp dev server.py. Open the inspector and call each tool with a realistic input.✓ 복사됨

→ Tools return expected JSON, no stack traces

결과: A working MCP server you can point Claude Desktop or any MCP client at.

함정

Secrets leak into tool descriptions because you printed them in docstrings — Use docstrings to describe behavior, not examples with real tokens. Load secrets via os.environ and never echo them in errors
Async + sync mixed, causes event loop errors — Pick one — if your HTTP client is async, make the whole tool async; don't call asyncio.run inside a tool

Expose company docs as MCP resources for RAG

👤 Platform engineers building agent infra ⏱ ~30 min intermediate

언제 쓸까: You want the agent to auto-discover and pull company knowledge without tool calls for every file.

흐름

Define a resource listing

Define a FastMCP resource at URI docs://{path} that lists all markdown files under ./docs/ and returns their content on read.✓ 복사됨

→ Resource registered, inspector shows list
Add a template resource

Add a resource template docs://{category}/{slug} that returns the matching file. Document valid {category} values.✓ 복사됨

→ Template registered, parameterized fetches work
Test in a real client

Connect Claude Desktop to the server. Verify the Resources menu lists all docs and content loads.✓ 복사됨

→ Resources appear as attachable context

결과: A resource-backed knowledge surface the agent can pull from natively — cleaner than tool calls for static content.

함정

Large resource lists overwhelm the client's UI — Paginate or filter in your list endpoint; not every file needs to be surfaced

Deploy a FastMCP server as a remote SSE endpoint

👤 Platform engineers serving multiple teams ⏱ ~60 min advanced

언제 쓸까: Multiple devs need the same MCP — host it once, don't make everyone run stdio locally.

사전 조건

A container host (Cloud Run, Fly, Railway) — Any Docker-capable runtime works

흐름

Switch transport to SSE

Modify server.py to run mcp.run(transport='sse', host='0.0.0.0', port=8080). Add a minimal Dockerfile.✓ 복사됨

→ Local curl localhost:8080/sse shows SSE handshake
Deploy behind auth

Deploy to Cloud Run with IAM auth. Front the /sse endpoint with a header-based auth check in a FastAPI middleware.✓ 복사됨

→ Public URL with 401 on unauth'd requests
Wire clients

Share the connection command with teammates: npx -y mcp-remote https://mcp.acme.com/sse. Verify their Claude Desktop picks up the tools.✓ 복사됨

→ Team members' clients see the same tools

결과: A shared remote MCP — one codebase, many users, easy to update.

함정

SSE connections drop behind some corporate proxies — Use streamable HTTP transport instead (newer spec) or document a VPN/direct-path requirement

함께 쓰기: cloud-run

조합

다른 MCP와 조합해 10배 효율

fastmcp + cloud-run

Build once, deploy to Cloud Run, share with the team

Wrap my internal pricing API as a FastMCP server, containerize it, and deploy to Cloud Run with IAM auth.✓ 복사됨

fastmcp + fastapi-mcp

Compare approaches — FastMCP for greenfield, fastapi-mcp for existing FastAPI apps

I have an existing FastAPI service. Should I add fastapi-mcp to expose it or rewrite in FastMCP? Compare based on my routes.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
@mcp.tool	decorated function with typed signature	Wrap any function you want agents to call	free
@mcp.resource	URI template + function	Expose readable content (docs, config, data snapshots)	free
@mcp.prompt	decorated function returning Message[]	Provide reusable multi-turn prompt scaffolds to clients	free
mcp.run	transport: 'stdio'\|'sse'\|'streamable-http', host?, port?	Entry point — call at end of your main script	free
Context (ctx) parameter	inject ctx: Context into any tool	Long-running tools that need to stream progress or log	free

비용 및 제한

운영 비용

API 쿼터: None — this is a framework, not a service
호출당 토큰: Your server runs any LLM calls; framework overhead is negligible
금액: Free, open source
팁: Use resources instead of tools for static content — resources are cheaper in tokens because they're pre-declared

보안

권한, 시크릿, 파급범위

자격 증명 저장: Your choice — env vars are idiomatic; load secrets at process start, not per call

데이터 외부 송신: Wherever your tool functions reach out to

문제 해결

자주 발생하는 오류와 해결

Tool schema missing required fields in the client

Your function params need type hints. Plain def foo(x) generates a useless schema — use def foo(x: str) with a docstring.

확인: Run `uv run mcp dev server.py` and check the Inspector's tool schema

Server starts but client sees 0 tools

You're mixing stdio with SSE misconfiguration. For Claude Desktop use transport='stdio'; for mcp-remote use 'sse'.

`ImportError: No module named 'fastmcp'`

Install with uv pip install fastmcp or add to pyproject.toml dependencies. Check that you're running the server from the same venv.

확인: uv pip show fastmcp

Async tool hangs on first call

You imported sync httpx inside an async tool. Use httpx.AsyncClient with async with — never mix.

대안

FastMCP 다른 것과 비교

대안	언제 쓰나	단점/장점
TypeScript MCP SDK	You're a TS/Node shop and want to stay there	Official, well-maintained, similar DX — just different language
fastapi-mcp	You already have a FastAPI app and want to expose routes as tools	Less control over the MCP surface but zero-refactor for existing services
csharp-sdk	.NET shop	First-party, but smaller ecosystem of examples

FastMCP

왜 쓰나요

핵심 기능

라이브 데모

실제 사용 모습

설치

클라이언트 선택

사용 사례

실전 활용법: FastMCP

Expose an internal REST API as an MCP in under an hour

사전 조건

흐름

함정

Expose company docs as MCP resources for RAG

흐름

함정

Deploy a FastMCP server as a remote SSE endpoint

사전 조건

흐름

함정

조합

다른 MCP와 조합해 10배 효율

도구

이 MCP가 노출하는 것

비용 및 제한

운영 비용

보안

권한, 시크릿, 파급범위

문제 해결

자주 발생하는 오류와 해결

대안

FastMCP 다른 것과 비교

더 보기

리소스