MCP Server Card: cách AI client tìm server MCP của bạn

Câu trả lời ngắn: một MCP Server Card là tệp JSON nhỏ cho MCP client (Claude, IDE, agent) biết server MCP từ xa của bạn ở đâu và cách kết nối — trước khi kết nối. Theo SEP-2127 (chính thức từ 6/10/2026), client tìm card qua một AI Catalog tại /.well-known/ai-catalog.json, trả về với Content-Type: application/ai-catalog+json. Card cần bốn trường: $schema, name, version, description (tối đa 100 ký tự), cộng mảng remotes với URL của server. Card không liệt kê tools.

MCP Server Card giải quyết vấn đề gì

MCP (Model Context Protocol) là cách AI client gọi công cụ của một dịch vụ. Với server MCP từ xa, người dùng hiện phải chép URL vào từng client bằng tay, rồi tự tìm xem cần header xác thực nào. Client chỉ biết server hỗ trợ gì sau khi đã kết nối.

SEP-2127 thêm một bước trước khi kết nối. Client nhận một tên miền, đọc catalog, rồi đọc card: URL của server, kiểu transport, header cần có. Nhờ đó client tự cấu hình được, và registry có thể lập chỉ mục server. Cách làm giống API catalog cho API (xem bài hướng dẫn API catalog) và Agent Skills cho skill (xem bài Agent Skills Discovery).

Hai tệp: catalog và card

Đây là catalog của GitHub, tải ngày 24/10/2026:

GET https://github.com/.well-known/ai-catalog.json
Content-Type: application/ai-catalog+json

{"specVersion": "1.0",
 "entries": [
  {"identifier": "urn:air:github.com:mcp:github-mcp-server",
   "type": "application/mcp-server-card+json",
   "url": "https://api.githubcopilot.com/mcp/server-card"}
 ]}

Mục trong catalog trỏ tới card trên một máy chủ khác. Card (rút gọn):

{"$schema": "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json",
 "name": "io.github.github/github-mcp-server",
 "version": "github-mcp-server/remote-792df72d…",
 "title": "GitHub",
 "description": "Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.",
 "remotes": [{"type": "streamable-http", "url": "https://api.githubcopilot.com/mcp/"}]}

Các quy tắc chính trong đặc tả:

• Catalog có specVersion và mảng entries. Mục MCP có type là application/mcp-server-card+json, một identifier, và đúng một trong hai: url (card nằm nơi khác, host nào cũng được) hoặc data (card nằm ngay trong catalog).
• $schema phải đúng URL schema server-card /v1/.
• name có dạng namespace/name với một dấu gạch chéo; namespace thường là tên miền đảo ngược, ví dụ com.example.
• version là một phiên bản cụ thể, không phải khoảng như ^1.2.0.
• description dài 1–100 ký tự.
• remotes liệt kê endpoint. Mỗi endpoint có type (streamable-http hoặc sse) và url.
• Header bắt buộc, ví dụ API key, khai báo trong headers của remote và có thể đánh dấu isSecret.
• Vị trí mặc định dành riêng cho card là <URL MCP>/server-card.

Vì sao card không có danh sách tools

Nhiều bản nháp cũ đặt danh sách tools vào tệp. SEP-2127 bỏ chúng đi có chủ đích. Tools, resources và prompts có thể khác theo người dùng, phiên, cấu hình và tính năng đang bật. Một tệp tĩnh không mô tả đúng được, và client có thể tin vào thông tin sai khi quyết định quyền truy cập. Vì vậy client lấy tools bằng tools/list sau khi kết nối, với danh tính của người dùng. Card chỉ trả lời: kết nối vào đâu, bằng cách nào.

Chúng tôi kiểm tra 8 website

Ngày 24/10/2026, chúng tôi chạy bộ chấm của bản quét CiteStat (packages/core/mcp-server-card.ts) trên 8 website:

Website	Kết quả	Mức
github.com	Đạt — catalog → card trên api.githubcopilot.com, 1 remote	Đạt
developers.cloudflare.com	Catalog đúng, 7 remote, nhưng description của card dài 355 ký tự (tối đa 100)	Trung bình
blog.cloudflare.com	Card ở đường dẫn bản nháp cũ /.well-known/mcp/server-card.json, không có catalog; description 131 ký tự	Thấp
isitagentready.com	Đường dẫn bản nháp cũ, dạng serverInfo cũ, có danh sách tools	Thấp
vercel.com	Catalog 6 mục, không mục nào là card MCP	Thấp
citestat.com (trước khi sửa)	Chỉ có /.well-known/mcp.json cũ	Thấp
erpfit.com	Không có	Thấp
docs.stripe.com	Không có	Thấp

Ngày 24/10/2026, 1 trong 8 website (github.com) công bố MCP Server Card hợp lệ; developers.cloudflare.com trượt vì description dài 355 ký tự. Một lần chạy lại cùng phút gặp lỗi hết thời gian chờ mạng, và bộ chấm khi đó báo như không có tệp; bảng trên là lần chạy đầu, đầy đủ. Các phát hiện khác:

• developers.cloudflare.com làm đúng luồng nhưng sai một trường. Catalog của developers.cloudflare.com liệt kê cả OpenAPI, chỉ mục Agent Skills, llms.txt và card MCP. Card trỏ tới 7 server, nhưng description dài 355 ký tự. Schema v1 giới hạn 100 ký tự, nên client kiểm tra schema sẽ từ chối card.
• Vercel có catalog nhưng không có card. Mục MCP duy nhất là metadata OAuth của mcp.vercel.com, khai báo là application/json. Client theo SEP-2127 chỉ chọn mục kiểu application/mcp-server-card+json, nên không tìm thấy server.
• Một trang kiểm tra agent-readiness vẫn dùng đường dẫn cũ. isitagentready.com đặt card tại /.well-known/mcp/server-card.json theo bản nháp trước của SEP-2127, và vẫn yêu cầu đường dẫn đó khi chấm website khác. Bản chính thức không đặt card ở đó.

Hiện nay client nào đọc catalog?

Đến ngày 24/10/2026, chúng tôi chưa thấy client MCP lớn nào ghi trong tài liệu rằng nó tự đọc /.well-known/ai-catalog.json. SDK C# chính thức mới có một issue theo dõi (#1912). Một số server đi trước: GitHub công bố card hợp lệ và developers.cloudflare.com có catalog, nhưng 6 trong 8 website chúng tôi kiểm tra chưa có card hợp lệ. Công bố bây giờ chỉ tốn một tệp JSON; lợi ích phụ thuộc vào việc client áp dụng.

Lỗi của chính chúng tôi

Trước ngày 24/10/2026, bản quét CiteStat chấm sai mục này theo cả hai chiều. Nó cho đạt bất kỳ JSON nào tại /.well-known/mcp.json hoặc mcp-server.json, và không đọc AI Catalog. Kết quả: github.com bị báo "không có card", còn citestat.com đạt nhờ một tệp mcp.json ghi transport chỉ là stdio — trong khi chúng tôi có server Streamable HTTP tại /api/mcp. Chúng tôi đã sửa bộ chấm theo SEP-2127 và công bố catalog của chính mình: card nằm ngay trong catalog (data), trỏ tới /api/mcp, khai báo header Authorization là bắt buộc và bí mật. Một bài kiểm tra tự động chạy bộ chấm của bản quét trên catalog đó.

Cách công bố card trong ba bước

1. Viết card. $schema v1, name dạng com.example/ten-server, version bằng phiên bản server trả về khi initialize, description dưới 100 ký tự, và remotes với URL thật. Nếu cần API key, khai báo trong headers.
2. Đặt card tại <URL MCP>/server-card với application/mcp-server-card+json, hoặc nhúng thẳng vào catalog bằng data.
3. Viết catalog tại /.well-known/ai-catalog.json với application/ai-catalog+json, một mục có identifier (ví dụ urn:air:example.com:mcp:ten-server) và type application/mcp-server-card+json. Nên bật CORS (Access-Control-Allow-Origin: *) để client chạy trong trình duyệt đọc được.

Nếu bạn không có server MCP từ xa, hãy bỏ qua phần này. Server chỉ chạy cục bộ (stdio) không có gì để client kết nối qua mạng.

CiteStat kiểm tra những gì

Trong thẻ Agent Readiness, bản quét đọc /.well-known/ai-catalog.json, chọn các mục MCP và đọc tối đa 5 card (trong catalog, hoặc tải từ url — chỉ địa chỉ công khai). Đạt khi có một card hợp lệ theo schema v1 và có ít nhất một remote. Catalog hỏng hoặc card sai schema là mức trung bình. Card không có remote, catalog không có mục MCP, hoặc chỉ có tệp ở đường dẫn bản nháp cũ là mức thấp. Mục này không đổi điểm SEO tổng. Bạn có thể tự kiểm tra website của mình miễn phí, 10 lượt mỗi ngày; nếu bạn kiểm tra website khách hàng hằng tuần, gói Pro cho 100 lượt mỗi ngày với giá 500.000₫/tháng (chưa VAT) — xem bảng giá.

Câu hỏi thường gặp

Website không có server MCP có cần card không?

Không. Card mô tả một server MCP từ xa mà client kết nối được. Không có server thì không có gì để mô tả, và một card bịa ra còn tệ hơn không có. Vì vậy bản quét CiteStat chỉ báo thiếu card ở mức thấp.

Vì sao card không liệt kê tools?

Vì tools có thể khác theo người dùng và phiên, nên client lấy chúng bằng tools/list sau khi kết nối. SEP-2127 cố ý bỏ tools, resources và prompts khỏi card.

Có thể giữ /.well-known/mcp.json không?

Có thể, cho client cũ, nhưng nó không thay được AI Catalog. Đề xuất mcp.json (SEP-1649) đã đóng, và client theo SEP-2127 chỉ đọc /.well-known/ai-catalog.json. Chúng tôi giữ tệp cũ và công bố card trong catalog.

MCP Server Card có giúp tăng thứ hạng Google không?

Tài liệu của Google không nhắc đến MCP Server Card. Card giúp client MCP tự cấu hình, không phải tín hiệu xếp hạng. Bản quét CiteStat chỉ tính nó trong thẻ Agent Readiness; điểm SEO tổng không đổi.

Nguồn: SEP-2127: MCP Server Cards (Final, hợp nhất 6/10/2026) · ext-server-card (schema.ts, docs/discovery.md) · AI Catalog · RFC 8615 (Well-Known URIs). Dữ liệu 8 website: tải ngày 24/10/2026.