Máy chủ FastAPI MCP là một công cụ cách mạng giúp kết nối giữa các ứng dụng FastAPI của bạn và các tác nhân AI sử dụng Giao thức Ngữ cảnh Mô hình (MCP). Trong kỷ nguyên mà sự tích hợp AI ngày càng trở nên quan trọng, giải pháp không cần cấu hình này cho phép bạn công khai các điểm cuối FastAPI hiện có của bạn như là các công cụ có thể được khám phá và sử dụng bởi các mô hình và tác nhân AI với nỗ lực tối thiểu.
Giới thiệu về FastAPI MCP
Giao thức Ngữ cảnh Mô hình (MCP) là một tiêu chuẩn mới nổi cho phép các mô hình AI tương tác với các công cụ và tài nguyên bên ngoài. Máy chủ FastAPI MCP đóng vai trò như một cầu nối giữa các ứng dụng FastAPI hiện có của bạn và các tác nhân AI tương thích với MCP như Claude của Anthropic, Cursor IDE, và những người khác, mà không cần bạn phải viết lại API hoặc học các khung làm việc phức tạp.
Điều làm cho FastAPI MCP thực sự nổi bật là cách tiếp cận không cần cấu hình của nó. Nó tự động chuyển đổi các điểm cuối FastAPI hiện có của bạn thành các công cụ tương thích với MCP, bảo tồn các sơ đồ điểm cuối, tài liệu và chức năng của bạn. Điều này có nghĩa là các tác nhân AI có thể khám phá và tương tác với các API của bạn với sự thiết lập tối thiểu từ phía bạn.
Bạn có thể tìm repository máy chủ FastAPI MCP tại: https://github.com/tadata-org/fastapi_mcp
Bắt đầu với FastAPI MCP
Cài đặt
Trước khi bạn có thể sử dụng FastAPI MCP, bạn sẽ cần cài đặt nó. Các nhà phát triển khuyên dùng uv, một trình cài đặt gói Python nhanh, nhưng bạn cũng có thể dùng phương pháp truyền thống pip:
Sử dụng uv:
uv add fastapi-mcp
Sử dụng pip:
pip install fastapi-mcp
Cài đặt cơ bản
Sự tích hợp FastAPI MCP với ứng dụng FastAPI hiện có của bạn không thể đơn giản hơn. Dưới đây là cài đặt cơ bản nhất:
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
# Ứng dụng FastAPI hiện có của bạn
app = FastAPI()
# Tạo máy chủ MCP
mcp = FastApiMCP(
app,
name="My API MCP",
description="Mô tả API của tôi",
base_url="http://localhost:8000" # Quan trọng cho việc định tuyến yêu cầu
)
# Gắn máy chủ MCP vào ứng dụng FastAPI của bạn
mcp.mount()
Chỉ vậy thôi! Với đoạn mã đơn giản này, máy chủ MCP của bạn giờ đã có sẵn tại https://app.base.url/mcp. Khi một khách hàng tương thích với MCP kết nối tới điểm cuối này, nó sẽ tự động phát hiện tất cả các tuyến FastAPI của bạn như là các công cụ có sẵn.
Hiểu về Tên công cụ MCP và ID hoạt động
Khi FastAPI MCP công khai các điểm cuối của bạn như là các công cụ, nó sử dụng operation_id từ các tuyến FastAPI của bạn như là tên công cụ MCP. FastAPI tự động tạo ra những ID này khi không được cung cấp rõ ràng, nhưng chúng có thể rất khó hiểu và kém thân thiện với người dùng.
So sánh hai cách tiếp cận này:
# ID hoạt động tự động tạo (kém thân thiện với người dùng)
@app.get("/users/{user_id}")
async def read_user(user_id: int):
return {"user_id": user_id}
# ID hoạt động rõ ràng (thân thiện hơn với người dùng)
@app.get("/users/{user_id}", operation_id="get_user_info")
async def read_user(user_id: int):
return {"user_id": user_id}
Trong ví dụ đầu tiên, công cụ có thể được đặt tên gì đó giống như "read_user_users__user_id__get", trong khi ví dụ thứ hai sẽ đơn giản là "get_user_info". Để cải thiện tính sử dụng, đặc biệt là khi các tác nhân AI tương tác với các công cụ của bạn, nên định nghĩa rõ ràng các ID hoạt động một cách rõ ràng và mô tả.
Tùy chọn cấu hình nâng cao
FastAPI MCP cung cấp một số tùy chọn tùy chỉnh để điều chỉnh cách API của bạn được công khai tới các khách hàng MCP.
Tùy chỉnh mô tả sơ đồ
Bạn có thể kiểm soát lượng thông tin được đưa vào mô tả công cụ:
mcp = FastApiMCP(
app,
name="My API MCP",
base_url="http://localhost:8000",
describe_all_responses=True, # Bao gồm tất cả các sơ đồ phản hồi có thể
describe_full_response_schema=True # Bao gồm chi tiết sơ đồ JSON đầy đủ
)
Lọc các điểm cuối
Bạn có thể muốn kiểm soát những điểm cuối nào được công khai như là các công cụ MCP. FastAPI MCP cung cấp một số cơ chế lọc:
# Chỉ bao gồm các hoạt động cụ thể theo ID hoạt động
mcp = FastApiMCP(
app,
include_operations=["get_user", "create_user"]
)
# Loại trừ các hoạt động cụ thể
mcp = FastApiMCP(
app,
exclude_operations=["delete_user"]
)
# Lọc theo thẻ
mcp = FastApiMCP(
app,
include_tags=["users", "public"]
)
# Loại trừ theo thẻ
mcp = FastApiMCP(
app,
exclude_tags=["admin", "internal"]
)
# Kết hợp các chiến lược lọc
mcp = FastApiMCP(
app,
include_operations=["user_login"],
include_tags=["public"]
)
Lưu ý rằng bạn không thể kết hợp các bộ lọc bao gồm và loại trừ của cùng một loại (hoạt động hoặc thẻ), nhưng bạn có thể sử dụng các bộ lọc hoạt động cùng với các bộ lọc thẻ.
Chiến lược triển khai
FastAPI MCP mang lại sự linh hoạt trong cách bạn triển khai máy chủ MCP của bạn.
Gắn vào ứng dụng gốc
Cách đơn giản nhất là gắn máy chủ MCP trực tiếp vào ứng dụng FastAPI gốc của bạn như đã trình bày trong ví dụ cơ bản. Điều này tạo ra một điểm cuối tại /mcp trong ứng dụng hiện có của bạn.
Triển khai như một dịch vụ riêng biệt
Bạn cũng có thể tạo một máy chủ MCP từ một ứng dụng FastAPI và gắn nó vào một ứng dụng khác, cho phép bạn triển khai API và giao diện MCP của nó riêng biệt:
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
# Ứng dụng API gốc của bạn
api_app = FastAPI()
# Định nghĩa các điểm cuối của bạn ở đây...
# Một ứng dụng riêng biệt cho máy chủ MCP
mcp_app = FastAPI()
# Tạo máy chủ MCP từ ứng dụng API
mcp = FastApiMCP(
api_app,
base_url="http://api-host:8001" # URL mà ứng dụng API sẽ chạy
)
# Gắn máy chủ MCP vào ứng dụng riêng biệt
mcp.mount(mcp_app)
# Bây giờ chạy cả hai ứng dụng riêng biệt:
# uvicorn main:api_app --host api-host --port 8001
# uvicorn main:mcp_app --host mcp-host --port 8000
Sự tách biệt này có thể hữu ích cho việc quản lý tài nguyên, bảo mật và mở rộng quy mô.
Cập nhật MCP sau khi thêm các điểm cuối mới
Nếu bạn thêm điểm cuối vào ứng dụng FastAPI của mình sau khi tạo máy chủ MCP, bạn sẽ cần làm mới máy chủ để bao gồm chúng:
# Thiết lập ban đầu
app = FastAPI()
mcp = FastApiMCP(app)
mcp.mount()
# Sau đó, thêm một điểm cuối mới
@app.get("/new/endpoint/", operation_id="new_endpoint")
async def new_endpoint():
return {"message": "Xin chào, thế giới!"}
# Làm mới máy chủ MCP để bao gồm điểm cuối mới
mcp.setup_server()
Kết nối tới máy chủ MCP của bạn
Khi ứng dụng FastAPI của bạn với tích hợp MCP đang chạy, các khách hàng có thể kết nối với nó theo nhiều cách khác nhau.
Sử dụng Sự kiện máy chủ gửi (SSE)
Nhiều khách hàng MCP, như Cursor IDE, hỗ trợ kết nối SSE:
- Chạy ứng dụng của bạn
- Trong Cursor → Cài đặt → MCP, sử dụng URL của điểm cuối máy chủ MCP của bạn (ví dụ:
http://localhost:8000/mcp) làm URL SSE - Cursor sẽ tự động phát hiện tất cả các công cụ và tài nguyên có sẵn
Sử dụng Proxy MCP cho các khách hàng không hỗ trợ SSE
Đối với các khách hàng không hỗ trợ SSE trực tiếp (như Claude Desktop):
- Chạy ứng dụng của bạn
- Cài đặt công cụ proxy MCP:
uv tool install mcp-proxy - Cấu hình khách hàng của bạn để sử dụng mcp-proxy
Đối với Claude Desktop trên Windows, hãy tạo một tệp cấu hình (claude_desktop_config.json):
{
"mcpServers": {
"my-api-mcp-proxy": {
"command": "mcp-proxy",
"args": ["http://127.0.0.1:8000/mcp"]
}
}
}
Đối với macOS, bạn sẽ cần chỉ định đường dẫn đầy đủ đến tệp thực thi mcp-proxy, mà bạn có thể tìm thấy bằng cách sử dụng which mcp-proxy.
Các trường hợp sử dụng thực tế
FastAPI MCP mở ra nhiều khả năng cho các ứng dụng dựa trên AI:
- Công cụ Phân tích Dữ liệu: Công khai các điểm cuối xử lý dữ liệu mà các tác nhân AI có thể sử dụng để phân tích dữ liệu người dùng mà không cần tích hợp tùy chỉnh cho mỗi mô hình AI.
- Các Hệ thống Quản lý Nội dung: Cho phép các công cụ AI truy xuất và cập nhật nội dung thông qua API CMS hiện có của bạn, làm cho việc tạo và quản lý nội dung trở nên hiệu quả hơn.
- Các Công cụ Tìm kiếm Tùy chỉnh: Cho phép các trợ lý AI tìm kiếm cơ sở dữ liệu hoặc kho nội dung chuyên biệt của bạn thông qua giao diện API đơn giản.
- Các Hoạt động Thương mại Điện tử: Để các tác nhân AI kiểm tra tồn kho, thông tin sản phẩm, hoặc đặt hàng thông qua các điểm cuối API thương mại điện tử hiện có của bạn.
- Xử lý Tài liệu: Cung cấp cho các công cụ AI khả năng tạo, chuyển đổi hoặc phân tích các tài liệu bằng cách sử dụng khả năng xử lý tài liệu backend của bạn.
Các Thực tiễn Tốt nhất
Để tận dụng tối đa FastAPI MCP, hãy xem xét những thực tiễn tốt nhất này:
- Sử dụng ID hoạt động rõ ràng: Định nghĩa các ID hoạt động rõ ràng, cụ thể cho tất cả các điểm cuối của bạn để làm cho chúng dễ sử dụng hơn bởi các tác nhân AI.
- Cung cấp tài liệu đầy đủ: Bao gồm các mô tả chi tiết cho mỗi điểm cuối và tham số để giúp các mô hình AI hiểu cách sử dụng các công cụ của bạn một cách hiệu quả.
- Sử dụng tên tham số nhất quán: Áp dụng quy ước đặt tên nhất quán cho các tham số tương tự trên các điểm cuối khác nhau.
- Xem xét các tác động về bảo mật: Cần chú ý đến những điểm cuối nào bạn công khai thông qua MCP và thực hiện xác thực phù hợp ở những nơi cần thiết.
- Theo dõi việc sử dụng: Theo dõi cách các tác nhân AI đang sử dụng các công cụ MCP của bạn để xác định các mẫu, lỗi hoặc các khu vực cần cải thiện.
Kết luận
Máy chủ FastAPI MCP đại diện cho một bước tiến quan trọng trong việc làm cho các dịch vụ backend có thể truy cập được cho các tác nhân AI. Bằng cách tự động chuyển đổi các điểm cuối FastAPI hiện có của bạn thành các công cụ tương thích với MCP mà không cần cấu hình, nó loại bỏ nhu cầu về các tích hợp tùy chỉnh hoặc điều chỉnh phức tạp cho thiết kế API của bạn.
Khi hệ sinh thái MCP tiếp tục phát triển và nhiều mô hình AI áp dụng tiêu chuẩn này, việc công khai các API của bạn thông qua FastAPI MCP sẽ giúp dịch vụ của bạn dễ dàng tiếp cận hơn đối với một loạt các tác nhân và công cụ AI. Bất kể bạn đang xây dựng công cụ nội bộ, dịch vụ cho lập trình viên hay API công cộng, FastAPI MCP cung cấp một con đường đơn giản để làm cho các dịch vụ của bạn có thể truy cập được bởi AI.
Bằng cách làm theo hướng dẫn trong bài viết này, bạn có thể nhanh chóng tích hợp FastAPI MCP vào các ứng dụng FastAPI hiện có của bạn và bắt đầu khám phá các khả năng của tự động hóa và tương tác dựa trên AI với các dịch vụ của bạn.