MCP Server Cards — AI용 robots.txt, 서버 능력을 자동으로 알리는 법

웹사이트에 robots.txt 있잖아요. 크롤러한테 "여기 와도 돼, 저기는 오지 마" 알려주는 파일이요.

MCP Server Cards는 이것의 AI 버전이에요.

기존:
개발자가 MCP 서버에 직접 연결해봐야
어떤 툴이 있는지 알 수 있음

MCP Server Cards:
.well-known/mcp.json 파일 하나로
연결 전에 서버 능력을 자동으로 공개

2026년 MCP 로드맵에 포함된 기능이에요. 아직 실험적이지만 방향이 명확해서 미리 알아두면 좋아요.

---

어떻게 생겼나

.well-known/mcp.json 파일이에요.

{
  "name": "My Backend MCP Server",
  "version": "1.2.0",
  "description": "PostgreSQL DB 조회, GitHub 이슈 관리, Slack 알림",
  "contact": "dev@mycompany.com",

  "tools": [
    {
      "name": "query_db",
      "description": "PostgreSQL SELECT 쿼리 실행",
      "category": "database",
      "readonly": true
    },
    {
      "name": "create_github_issue",
      "description": "GitHub 이슈 생성",
      "category": "project-management",
      "readonly": false
    },
    {
      "name": "send_slack_message",
      "description": "Slack 채널에 메시지 전송",
      "category": "communication",
      "readonly": false
    }
  ],

  "auth": {
    "type": "api-key",
    "header": "X-API-Key"
  },

  "endpoints": {
    "sse": "/sse",
    "health": "/health"
  },

  "security": {
    "readonly_by_default": true,
    "audit_logging": true,
    "rate_limit": "100/hour"
  }
}

---

왜 필요한가

현재 문제:

MCP 서버가 1만 개 넘게 생겼어요.
어떤 서버가 뭘 하는지 알려면
직접 연결해서 list_tools() 호출해야 함
→ 악성 서버 연결 위험
→ 검색/발견 불가능

Server Cards 있으면:

연결 전에 https://서버주소/.well-known/mcp.json 읽으면
- 어떤 툴 있는지
- 어떤 권한 필요한지
- 읽기 전용인지 쓰기도 되는지
- 인증 방식이 뭔지
→ 전부 파악 가능

---

실전 — 내 MCP 서버에 Server Cards 추가

기존 MCP 서버에 /well-known/mcp.json 엔드포인트 추가해요.

# server.py에 추가
from starlette.routing import Route
from starlette.responses import JSONResponse

async def server_card(request):
    return JSONResponse({
        "name": "Team Backend MCP",
        "version": "1.0.0",
        "description": "팀 DB 조회 및 GitHub/Slack 자동화",

        "tools": [
            {
                "name": "query_db",
                "description": "DB SELECT 쿼리 실행 (읽기 전용)",
                "readonly": True,
                "category": "database"
            },
            {
                "name": "create_issue",
                "description": "GitHub 이슈 생성",
                "readonly": False,
                "category": "project-management"
            }
        ],

        "auth": {
            "type": "api-key",
            "header": "X-API-Key"
        },

        "security": {
            "readonly_db": True,
            "audit_logging": True
        },

        "endpoints": {
            "sse": "/sse",
            "health": "/health"
        }
    })

# 라우팅에 추가
app = Starlette(
    routes=[
        Route("/.well-known/mcp.json", endpoint=server_card),  # ← 추가
        Route("/sse", endpoint=handle_sse),
        Route("/health", endpoint=lambda r: JSONResponse({"status": "ok"}))
    ]
)

---

Claude Code에서 활용

Server Cards가 있으면 연결 전에 미리 확인할 수 있어요.

# 연결 전 서버 능력 확인
curl https://team-mcp.mycompany.com/.well-known/mcp.json

# 출력:
# {
#   "name": "Team Backend MCP",
#   "tools": [...],
#   "auth": {"type": "api-key"},
#   "security": {"readonly_db": true}
# }

# 확인 후 안전하면 연결
claude mcp add team-mcp \
  --header "X-API-Key: mykey" \
  https://team-mcp.mycompany.com/sse

Tool Poisoning Attack 방어에도 도움 돼요. 연결 전에 툴 목록 미리 확인하고 의심스러우면 연결 안 하면 돼요.

---

MCP 레지스트리와 연동

Server Cards가 표준화되면 이런 게 가능해져요.

MCP 서버 레지스트리 (npmjs.com 같은 것):

검색: "database"
→ 검색 결과:
  - postgres-mcp v2.1 (읽기전용, 인기)
  - mysql-mcp v1.3 (읽기/쓰기, 검증됨)
  - mongodb-mcp v3.0 (읽기전용, 공식)

각 서버 Server Card 자동 표시
→ 연결 전 능력/보안 수준 확인 가능

---

현재 상태

✅ MCP 2026 로드맵에 공식 포함
✅ SEP(스펙 개선 제안) 작성 중
⚠️  아직 표준 확정 전
🔜 2026 하반기 정식 스펙 예정

지금 내 MCP 서버에 미리 .well-known/mcp.json 추가해 놓으면 나중에 표준 확정될 때 자동으로 호환돼요.