--- title: "Kết nối MCP cho AI agent" url: https://phatdev.net/docs/phatdev-portfolio/mcp lang: vi updated: 2026-10-21 alternate: en: https://phatdev.net/en/docs/phatdev-portfolio/mcp markdown: https://phatdev.net/docs/phatdev-portfolio/mcp.md --- # Kết nối MCP cho AI agent Thuộc bộ tài liệu: [phatdev.net](https://phatdev.net/docs/phatdev-portfolio.md) > Endpoint /api/mcp, 12 công cụ, Server Card, bản Markdown (.md), WebMCP và cách kết nối. ## Endpoint `https://phatdev.net/api/mcp` theo chuẩn **Model Context Protocol**, transport **Streamable HTTP** dạng stateless: gửi JSON-RPC 2.0 bằng POST, nhận `application/json`. Chỉ đọc, không cần khoá, giới hạn 120 yêu cầu mỗi phút mỗi IP (chỉnh được trong trang quản trị). Gọi GET để xem mô tả ngắn của server. ## Công cụ Mọi công cụ đều chỉ đọc (`readOnlyHint`) và chỉ trả nội dung đã công khai trên phatdev.net. Quản trị viên có thể tắt từng công cụ. | Tool | Tham số | Trả về | |---|---|---| | `search_site` | `query`, `lang`, `type`, `limit` | Tìm chung trong dự án, blog và docs: url, link Markdown và đoạn trích | | `get_page` | `url` | Markdown của một trang phatdev.net (chặn host khác) | | `get_profile` | `lang` | Hồ sơ, vai trò, kênh liên hệ | | `list_skills` | `lang` | Kỹ năng theo nhóm kèm dự án đã dùng | | `get_contact` | `lang` | Kênh liên hệ công khai (email, điện thoại, Telegram, Zalo, GitHub, LinkedIn, Facebook) và giờ làm việc 12:00-02:00 (giờ Việt Nam) | | `list_projects` | `lang` | Danh sách dự án, slug, link | | `get_project` | `slug`, `lang` | Bài phân tích dự án (markdown) | | `list_posts` | `lang`, `category`, `query`, `limit` | Danh sách bài blog song ngữ | | `get_post` | `slug`, `lang` | Nội dung bài blog (markdown) kèm nguồn tham khảo | | `list_docs` | `plugin` (tuỳ chọn), `lang` | Danh sách plugin hoặc bài tài liệu; `lang=en` chỉ liệt kê bài đã có bản dịch tiếng Anh (url trỏ tới `/en/docs`) | | `get_doc` | `plugin`, `slug`, `lang` | Nội dung bài tài liệu; `lang=en` trả bản tiếng Anh, bài chưa dịch thì báo lỗi (dùng `lang=vi`) | | `search_docs` | `query`, `plugin`, `lang` | Kết quả tìm trong tài liệu; `lang=en` chỉ tìm trong các bài đã dịch | Tham số `lang` nhận `vi` (mặc định) hoặc `en`. Riêng `search_site` bỏ trống `lang` thì tìm cả tiếng Việt lẫn tiếng Anh. Khi gọi `initialize`, server trả thêm trường `instructions` hướng dẫn agent: tìm bằng `search_site`, đọc trọn trang bằng `get_page`, giới thiệu bản thân bằng `get_profile`, `list_skills`, `get_contact`. ## Thêm vào Claude / client MCP Với client hỗ trợ MCP qua HTTP, khai báo một server kiểu remote trỏ tới URL trên, ví dụ: ```json { "mcpServers": { "phatdev": { "type": "http", "url": "https://phatdev.net/api/mcp" } } } ``` ## Gọi thử bằng curl ```bash curl -s https://phatdev.net/api/mcp \ -H 'content-type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_site","arguments":{"query":"recovery point"}}}' ``` ## Khám phá server (Server Card) Để client tự tìm ra endpoint mà không phải cấu hình tay, site công bố Server Card theo đề xuất SEP-2127 của MCP (tiêu chuẩn còn mới, có thể đổi): - `https://phatdev.net/api/mcp/server-card` (vị trí khuyến nghị: địa chỉ endpoint + `/server-card`) - `https://phatdev.net/.well-known/mcp/server-card.json` và `https://phatdev.net/.well-known/mcp-server-card` (cùng nội dung, cho client cũ) - `https://phatdev.net/.well-known/ai-catalog.json` (danh mục cấp domain trỏ tới Server Card) - `https://phatdev.net/.well-known/mcp` (manifest liệt kê endpoint, dạng đề xuất chưa thành chuẩn) Card ghi tên server, phiên bản, endpoint `streamable-http`, các phiên bản giao thức hỗ trợ; phần thông tin thêm của phatdev.net (xác thực: không, danh sách công cụ) nằm trong `_meta`. Các trang `/vi`, `/en`, `/llms.txt` và `/api/mcp` còn gửi header `Link: ; rel="mcp-server-card"` (cách báo hiệu đề xuất của site, không có trong spec). ## Bản Markdown của từng trang Mọi trang nội dung có bản Markdown sạch (có front-matter: tiêu đề, URL gốc, ngôn ngữ, ngày cập nhật, link bản ngôn ngữ kia): - Thêm `.md` vào URL: `https://phatdev.net/vi.md`, `/en.md`, `/vi/projects.md`, `/vi/projects/.md`, `/vi/blog.md`, `/vi/blog/.md`, `/docs.md`, `/docs//.md`, `/en/docs//.md` (chỉ bài đã dịch), `/sl-migrations.md`. - Hoặc gửi header `Accept: text/markdown` tới URL trang thường: server trả Markdown thay vì HTML. - `https://phatdev.net/llms.txt` là mục lục cho agent; toàn bộ nội dung công khai được gộp theo ngôn ngữ trong hai tệp: `https://phatdev.net/llms-full-vi.txt` (tiếng Việt) và `https://phatdev.net/llms-full-en.txt` (tiếng Anh, phần tài liệu chỉ gồm bài đã dịch), mỗi tệp gồm hồ sơ, dự án, blog và tài liệu của ngôn ngữ đó. `https://phatdev.net/llms-full.txt` là mục lục ngắn trỏ tới hai tệp này. Bản `.md` có header `Link: ; rel="canonical"` nên Google gộp về trang gốc. Lượt tải `.md` không tính vào thống kê người xem, chỉ ghi vào số liệu API. ## WebMCP (agent duyệt web trong trình duyệt) Nếu trình duyệt của agent hỗ trợ WebMCP (tính năng thử nghiệm: Chrome 149 có origin trial, hoặc bật cờ `chrome://flags/#enable-webmcp-testing`), mỗi trang đăng ký các công cụ qua `document.modelContext` để agent thao tác ngay trên trang: | Công cụ | Việc làm | Chỉ đọc | |---|---|---| | `search_site` | Tìm trong dự án, blog, docs | Có | | `get_current_page_markdown` | Lấy bản Markdown của trang đang mở | Có | | `list_posts` | Liệt kê bài blog | Có | | `open_page` | Chuyển tới trang khác của site (chặn /admin, /api) | Không | | `set_language` | Đổi ngôn ngữ vi/en | Không | | `set_theme` | Đổi giao diện sáng/tối | Không | | `prefill_contact_form` | Mở form yêu cầu dự án nhiều bước và điền sẵn loại việc, loại sản phẩm, tính năng, tuỳ chọn AI, ngân sách, thời gian, mô tả, thông tin liên hệ | Không | `prefill_contact_form` chỉ mở form yêu cầu dự án (nhiều bước) trên trang và điền sẵn các trường bạn truyền vào; trường nào không truyền thì để trống cho người dùng chọn. Người dùng phải tự xem lại và bấm Gửi. Không có công cụ nào gửi tin hay ghi dữ liệu thay người dùng. Trình duyệt không hỗ trợ WebMCP thì không tải thêm gì. ## Ghi chú - Gửi `initialize` trước nếu client yêu cầu; server hỗ trợ protocol 2025-06-18, 2025-03-26, 2024-11-05. - GET với `Accept: text/event-stream` trả 405 vì server không mở luồng SSE.