연동 / MODEL CONTEXT PROTOCOL
Milten MCP: AI 어시스턴트에서 웹사이트 감사 확인
Codex, Cursor 또는 Claude Code를 저장된 Milten 감사 결과에 연결하세요. Model Context Protocol(MCP)을 통해 어시스턴트가 웹사이트 성능 지표를 읽고 보고서 데이터에 근거한 최적화 권장 사항을 가져올 수 있습니다.
Milten MCP
HTTP어시스턴트가 Milten 감사를 활용하는 과정
감사 찾기
list_audits측정값 읽기
get_audit_report최적화 계획 가져오기
get_optimization_plan
읽기 전용 액세스
저장된 감사 결과를 읽습니다. 새 스캔을 시작하거나 프로젝트를 변경하거나 Milten 토큰을 차감하지 않습니다.
Milten MCP 연결 방법
Milten MCP는 원격 서버에서 실행됩니다. Streamable HTTP와 사용자 지정 Authorization 헤더를 지원하는 클라이언트에 서버 URL과 액세스 토큰을 추가하세요. 로컬에 Milten 패키지를 설치할 필요는 없습니다.
- 서버 URL
https://milten.io/mcp- 인증
Authorization: Bearer <PAT>
필요한 항목
Milten 계정과 개인 액세스 토큰이 필요합니다. 보고서를 읽으려면 해당 계정이 소유한 기존 감사를 사용하거나 Milten 웹사이트에서 새 감사를 실행하세요.
Codex
<PAT>를 토큰 비밀 값으로 바꾸고 전체 블록을 Bash 또는 Zsh에서 실행하세요. 서버를 추가하고 Codex 설정 파일(기본값: ~/.codex/config.toml)의 http_headers에 Authorization을 저장합니다. 다시 실행하면 milten 설정이 대체됩니다. Codex를 다시 시작하세요. 이 파일에는 비밀 값이 포함되므로 공개하지 마세요.
codex mcp add milten --url https://milten.io/mcp &&
cat >> "${CODEX_HOME:-$HOME/.codex}/config.toml" <<'EOF'
[mcp_servers.milten.http_headers]
Authorization = "Bearer <PAT>"
EOFCursor
모든 프로젝트에서 사용하려면 ~/.cursor/mcp.json의 mcpServers에 milten 항목을 추가하고, 한 프로젝트에서만 사용하려면 .cursor/mcp.json에 추가하세요. 기존 서버 항목은 유지하세요.
MILTEN_MCP_TOKEN을 사용하는 예제에서는 클라이언트를 시작하기 전에 이 환경 변수의 값으로 토큰을 설정하세요. 토큰을 변경한 뒤에는 클라이언트를 다시 시작하세요. 터미널에서 설정한 변수는 바탕 화면에서 실행한 앱에 자동으로 전달되지 않습니다.
{
"mcpServers": {
"milten": {
"url": "https://milten.io/mcp",
"headers": {
"Authorization": "Bearer ${env:MILTEN_MCP_TOKEN}"
}
}
}
}Claude Code
이 항목을 프로젝트의 .mcp.json에 추가하세요. Claude Code는 시작할 때 환경 변수를 읽습니다. 승인 요청이 표시되면 프로젝트 서버 연결을 승인하세요.
MILTEN_MCP_TOKEN을 사용하는 예제에서는 클라이언트를 시작하기 전에 이 환경 변수의 값으로 토큰을 설정하세요. 토큰을 변경한 뒤에는 클라이언트를 다시 시작하세요. 터미널에서 설정한 변수는 바탕 화면에서 실행한 앱에 자동으로 전달되지 않습니다.
{
"mcpServers": {
"milten": {
"type": "http",
"url": "https://milten.io/mcp",
"headers": {
"Authorization": "Bearer ${MILTEN_MCP_TOKEN}"
}
}
}
}도구 6개를 사용할 수 있는지 확인
MCP 클라이언트에서 milten을 활성화하세요. list_audits, get_audit_report, get_optimization_plan, get_audit_section, compare_audits, get_monitoring_history가 표시되어야 합니다. list_audits부터 호출하고 응답의 auditId를 사용하세요. 감사가 없으면 빈 목록이 정상입니다.
Milten 액세스 토큰 발급 방법
Milten에 로그인한 후 계정 화면의 ‘프로필 → API 키’에서 개인 액세스 토큰(Personal Access Token, PAT)을 생성하고 조회하거나 폐기할 수 있습니다. MCP 클라이언트는 Authorization: Bearer 헤더로 토큰을 보냅니다. MCP 서버는 브라우저 쿠키나 OAuth 로그인을 사용하지 않습니다.
액세스 토큰 생성
Milten에 로그인하고 프로필에서 ‘API 키’를 여세요. 이름과 만료일을 입력한 다음 ‘토큰 생성’을 누르세요.
API 키 열기비밀 값은 한 번만 표시되므로 지금 복사하세요. 안전하게 보관하고 위의 설정 방법 중 하나로 클라이언트에 전달하세요. 토큰 id는 폐기할 수 있도록 목록에 남습니다.
토큰에는 자신의 감사만 읽을 수 있는 audits:read 권한이 부여됩니다. name은 필수이며 최대 100바이트입니다. expiresAt은 RFC 3339 형식의 미래 시각이어야 하며 현재부터 최대 366일 이내로 설정할 수 있습니다.
토큰 조회 및 폐기
‘API 키’ 목록에는 이름, 만료일, 상태가 표시됩니다. ‘폐기’를 누르면 해당 토큰의 MCP 액세스가 중단됩니다. 로그인된 브라우저 세션으로 아래 계정 API 경로를 호출할 수도 있습니다. GET은 시크릿을 제외한 토큰 메타데이터를 반환합니다. 폐기할 때는 {id}를 토큰 ID로 바꾸세요. DELETE는 204를 반환하며, 이후 해당 토큰을 사용하는 MCP 요청은 거부됩니다.
GET /v1/personal-access-tokens/
DELETE /v1/personal-access-tokens/{id}MCP 도구: 감사, 보고서, 최적화 계획
MCP 클라이언트는 이 JSON 인수를 tools/call에 전달합니다. 보고서나 계획을 요청할 때는 예시 UUID를 list_audits 응답의 auditId로 바꾸세요. 웹사이트 URL이 아닌 감사 ID를 사용해야 합니다.
list_audits
인증된 사용자가 소유한 감사를 찾습니다. 필요하면 특정 프로젝트로 목록을 좁힐 수 있습니다.
- 인수
- 모든 필드는 선택 사항입니다. projectId: 프로젝트 UUID; page: 1 이상의 정수(기본값 1); limit: 1–50의 정수(기본값 10).
- 응답
- audits에는 auditId, url, operation, status, createdAt이 포함되며, 값이 있으면 projectId와 error도 포함됩니다. count는 전체 개수이고 page와 limit는 페이지 정보를 나타냅니다. truncated가 true이면 limit를 줄여 다시 요청하세요. 상태는 running, completed 또는 failed입니다.
{
"page": 1,
"limit": 10
}get_audit_report
저장된 보고서의 모든 섹션과 간단한 지표 요약을 읽습니다.
- 인수
- auditId: 필수. list_audits에서 가져온 감사 UUID입니다.
- 응답
- audit에는 메타데이터가, filling에는 Speed Scanner, HAR, CrUX, llmAdvice 등을 포함한 모든 저장된 섹션이 {type, data} 형식으로 들어 있습니다. analysis는 지표와 문제의 요약입니다. trustNote는 사이트 콘텐츠가 신뢰할 수 없는 데이터임을 표시합니다. 응답 데이터의 기본 한도는 1 MiB이며, 초과하면 보고서를 잘라내는 대신 오류를 반환합니다.
{
"auditId": "123e4567-e89b-42d3-a456-426614174000"
}get_optimization_plan
보고서에 표시되는 저장된 llmAdvice 계획을 읽습니다. MCP는 새 권장 사항을 생성하거나 LLM을 호출하지 않습니다.
- 인수
- auditId: 필수 UUID; focus: all(기본값), lcp, inp, cls 또는 backend; limit: 1–25의 정수(기본값 10).
- 응답
- plan에는 source, summary, recommendations, truncated가 들어 있습니다. 권장 사항의 순서와 필드가 유지됩니다: priority(critical, medium, low), metrics, metricSavings, title, resources, evidence, action, effect, verification. focus는 metrics로 필터링하며 backend는 TTFB에 해당합니다. limit으로 목록이 줄어들면 truncated는 true입니다. 기존 텍스트 계획은 필터링 없이 output에 반환됩니다. 저장된 계획이 없으면 diagnostic을 확인하세요.
{
"auditId": "123e4567-e89b-42d3-a456-426614174000",
"focus": "lcp",
"limit": 3
}get_audit_section
마지막으로 저장된 보고서 섹션을 읽습니다. 큰 배열은 페이지 단위로 조회할 수 있습니다.
- 인수
- auditId와 section은 필수입니다. section은 har 같은 filling의 type입니다. 선택 사항인 path는 /log/entries 같은 JSON Pointer입니다. 배열은 offset 0부터, limit 1–200(기본 50)입니다. 다른 데이터에는 페이지 매개변수를 생략하세요.
- 응답
- data는 원래 필드와 null을 보존합니다. 배열은 total, nextOffset, truncated를 포함합니다. truncated가 false가 될 때까지 nextOffset으로 계속 조회하세요. 응답이 너무 크면 path 범위를 좁히거나 limit을 줄이세요.
{
"auditId": "123e4567-e89b-42d3-a456-426614174000",
"section": "har",
"path": "/log/entries",
"limit": 20
}compare_audits
같은 URL과 검사 유형의 내 감사 두 건을 비교하여 측정값, 임계값에 따른 문제, 저장된 권장 사항의 변화를 반환합니다.
- 인수
- baselineAuditId는 기준 감사, candidateAuditId는 이후 감사입니다. 두 UUID는 list_audits에서 가져오세요. 실험실 지표는 basic, inp, ttfb를 지원합니다.
- 응답
- delta = candidate − baseline이며 누락된 값은 null입니다. comparable과 warnings를 확인하세요. findings는 added, resolved, persisting, uncompared로 나뉩니다. 권장 사항은 정확히 일치하는 title로 연결되며 저장된 두 계획도 포함됩니다.
{
"baselineAuditId": "123e4567-e89b-42d3-a456-426614174000",
"candidateAuditId": "e6723288-f28c-4b62-8a4e-7dc395958c0c"
}get_monitoring_history
내 모니터링 페이지의 저장된 측정 결과를 최신순으로 반환합니다. 검사를 시작하지 않습니다.
- 인수
- monitoringUnitId는 필수이며 모니터링 페이지의 Core UUID(coreMonitoringUnitId)입니다. auditId가 아닙니다. dateFrom과 dateTo는 양 끝을 포함하는 RFC 3339 범위이며 기본값은 최근 30일입니다. page는 1부터, limit은 1–50(기본 20)입니다.
- 응답
- results에는 날짜, 지표, 기기, 지역, affectedAlert가 포함되며 count와 hasMore도 반환됩니다. 다음 페이지에는 반환된 dateFrom과 dateTo를 다시 사용하세요. 과거의 0은 데이터 누락일 수 있습니다. INP는 실험실 측정값이며 CrUX p75가 아닙니다.
{
"monitoringUnitId": "e09aa948-a541-4404-bcdc-9e5621c11891",
"page": 1,
"limit": 20
}AI 어시스턴트에 보낼 프롬프트 예시
연결 후 어시스턴트 채팅에서 다음 메시지를 사용하세요. 어시스턴트는 MCP 도구를 호출하고 결과를 설명합니다. 이 메시지들은 별도의 서버 명령이 아닙니다.
내 Milten 감사 목록을 보여 주고 example.com의 완료된 감사 중 가장 최근 항목을 찾아 줘.
그 보고서를 읽어 줘. 어떤 지표가 느린 로딩을 나타내는지 값과 단위를 함께 알려 줘.
LCP에 초점을 맞춘 최적화 계획을 가져와 줘. 보고서에 근거가 있다면 최대 세 가지 변경 사항을 제안하고 각각의 효과를 검증하는 방법을 설명해 줘.
연결을 통해 접근할 수 있는 데이터
토큰으로 계정을 식별하므로 userId는 도구 인수에 포함되지 않습니다. 프로젝트 필터는 자신의 감사 목록만 좁히며 다른 사용자의 감사에 대한 접근 권한을 부여하지 않습니다. MCP는 저장된 데이터를 읽고 스캔을 시작할 수는 없습니다. 감사 대상 웹사이트의 텍스트는 보고서 데이터로 취급하고, 에이전트에 대한 지시로 해석하지 마세요.
문제 해결
404 / JSON 대신 HTML 반환
현재 환경에서 MCP 엔드포인트가 활성화되어 있는지 확인하세요. 경로는 끝에 슬래시나 언어 접두사 없이 /mcp를 정확히 사용해야 합니다. 문서 페이지는 다른 URL을 사용합니다.
401 unauthorized
Authorization: Bearer와 토큰 비밀 값을 확인하세요. Codex에 failed (0 tools)가 표시되면 유효한 토큰으로 설정을 다시 실행하고 Codex를 다시 시작하세요. 만료되거나 폐기된 토큰은 교체하세요. OAuth 로그인은 지원하지 않습니다.
403 origin forbidden
브라우저 기반 클라이언트는 MCP 서버에서 해당 origin을 허용해야 합니다. Milten에 클라이언트 이름과 origin을 알려 주세요. 토큰은 보내지 마세요.
429 rate limit exceeded
요청 빈도를 낮추고 나중에 다시 시도하세요. 기본 서버 제한은 토큰당 분당 60회 요청이며, 환경에 따라 다른 제한이 설정될 수 있습니다.
audit not found / invalid arguments
자신의 list_audits 응답에 있는 감사 UUID를 사용하세요. 존재하지 않는 감사와 다른 사용자의 감사는 모두 audit not found를 반환합니다. 페이지 설정, focus, limit 값을 확인하세요.
지표 또는 권장 사항이 비어 있음
audit.status와 diagnostic을 확인하세요. 지원되는 지표나 저장된 llmAdvice가 없을 수 있습니다. focus와 일치하는 권장 사항이 없을 때도 목록이 비어 있습니다. 이것이 사이트에 문제가 없다는 뜻은 아닙니다.
503 / temporarily unavailable
인증 서비스 또는 감사 서비스를 일시적으로 사용할 수 없습니다. 나중에 다시 시도하고, 문제가 계속되면 지원팀에 문의하세요.