Kết nối MCP cho AI agent

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ụ:

{
  "mcpServers": {
    "phatdev": { "type": "http", "url": "https://phatdev.net/api/mcp" }
  }
}

Gọi thử bằng curl

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: <https://phatdev.net/api/mcp/server-card>; 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/<slug>.md, /vi/blog.md, /vi/blog/<slug>.md, /docs.md, /docs/<plugin>/<slug>.md, /en/docs/<plugin>/<slug>.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: <URL trang HTML>; 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.