#mmcp 관리자 가이드

mmcp v1.0.1 관리자 가이드 — Mattermost MCP Gateway

이 문서는 폐쇄망(오프라인) 환경에 mmcp v1.0.1을 설치하고 운영하는 관리자를 위한 안내서입니다. 일반 사용자의 MCP 클라이언트 연결 방법은 콘솔의 내 공간 > MCP 연결 가이드 화면을 참고하세요.

#목차

1. 개요와 아키텍처
2. 설치 (오프라인)
3. 첫 설정 체크리스트
4. Keycloak 연동
5. Mattermost 연동
6. 사용자·역할
7. 계정 매핑과 충돌 처리
8. MCP 도구 정책
9. 데이터·호출 정책
10. 클라이언트·세션
11. 키 관리와 회전
12. 접근 제어
13. 감사 로그·승인 이력
14. 서버 로그
15. 백업·복원·업그레이드
16. 모니터링 엔드포인트
17. 문제 해결
18. 보안 체크리스트

#1. 개요와 아키텍처

mmcp는 Claude Code, Codex, Cursor, 사내 AI 포털 같은 MCP 클라이언트가 각 사용자 본인의 Mattermost 권한으로 메시지를 조회·검색하고 작성할 수 있게 해 주는 게이트웨이입니다.

• 인증: Keycloak OIDC(사일런트 SSO), mmcp 자체 OAuth 2.1 인가 서버, Keycloak 액세스 토큰 직접 검증, 개인 API 키를 지원합니다.
• 권한: 조회는 항상 사용자 본인의 Mattermost 자격증명으로 수행하므로 Mattermost 채널 멤버십이 그대로 적용됩니다. 그 위에 mmcp 역할, 도구 정책, 채널 유형 정책이 한 겹 더 적용됩니다.
• 구성: 단일 컨테이너(React 콘솔 + Go 서버)와 PostgreSQL만 있으면 됩니다. 환경변수는 4개뿐이며, 나머지 설정은 모두 관리 콘솔에서 관리하고 PostgreSQL에 저장합니다.

flowchart LR
    subgraph Clients["MCP 클라이언트"]
        CC["Claude Code / Codex / Cursor"]
        Portal["사내 AI 포털"]
    end
    Browser["브라우저<br/>(관리 콘솔 · 내 공간)"]

    subgraph mmcp["mmcp v1.0.1 컨테이너 :8080"]
        MCP["/mcp<br/>Streamable HTTP"]
        OAuth["/oauth/*<br/>OAuth 2.1 인가 서버"]
        Console["관리 콘솔 / API"]
        Policy["역할 · 도구 정책<br/>채널 정책 · 호출 한도 · 승인"]
        Keys["봉투 암호화<br/>마스터 키 → 데이터 키"]
    end

    KC["Keycloak<br/>(OIDC)"]
    MM["Mattermost<br/>REST API v4"]
    PG[("PostgreSQL<br/>설정 · 매핑 · 감사")]

    CC -- "OAuth 토큰 / API 키" --> MCP
    Portal -- "Keycloak 액세스 토큰" --> MCP
    CC -. "DCR · PKCE" .-> OAuth
    Browser --> Console
    Browser -. "로그인 (prompt=none)" .-> KC
    OAuth -. "사용자 인증" .-> KC
    MCP --> Policy
    Policy -- "사용자 본인 토큰<br/>(조회·작성)" --> MM
    Policy -- "서비스 토큰<br/>(디렉터리 조회·PAT 발급)" --> MM
    Policy -- "봇 토큰<br/>(봇 발신)" --> MM
    Keys --- PG
    Console --- PG

#콘솔 구성

콘솔은 관리 콘솔(admin 역할 전용)과 내 공간(모든 사용자)으로 나뉩니다.

내 공간에는 내 홈, MCP 연결 가이드, 내 API 키, Mattermost 연결, 개인 암호화 키, 도구 실행기, 승인 요청, 내 활동, 세션·연결된 앱, 프로필·환경설정이 있습니다.

#키보드 단축키

콘솔은 다크 모드와 모바일 화면을 지원합니다.

다크 모드	모바일	모바일 내비게이션

#2. 설치 (오프라인)

#2.1 사전 준비

이미지 특성(mmcp v1.0.1):

• 이미지 태그 mmcp:v1.0.1, linux/amd64, distroless static-debian12:nonroot 기반, 비루트 사용자로 실행
• 포트 8080, HEALTHCHECK는 /mmcp healthcheck (컨테이너 내부에서 http://127.0.0.1:8080/api/health 호출)
• 읽기 전용 루트 파일시스템 지원 (compose.offline.yml은 read_only: true, /tmp tmpfs, no-new-privileges, cap_drop: ALL로 실행)
• 시작 시 DB 마이그레이션을 자동 적용

#2.2 이미지 반입과 검증

# 무결성 확인 (GitHub 릴리스 노트에 적힌 SHA-256 값과 같아야 합니다)
sha256sum mmcp-v1.0.1.tar.gz   # 릴리스 노트의 SHA-256 값과 비교

# 이미지 로드 → "Loaded image: mmcp:v1.0.1"
docker load -i mmcp-v1.0.1.tar.gz

# 네트워크 없이 실행되는지 확인
docker run --rm --network none mmcp:v1.0.1 version

#2.3 환경변수 (.env)

mmcp가 읽는 환경변수는 정확히 4개입니다. 그 외 모든 설정은 관리 콘솔에서 합니다.

키 생성:

docker run --rm mmcp:v1.0.1 gen-key

.env 예시 (.env.example 기반):

POSTGRES_DSN=postgres://mmcp:change-me@postgres:5432/mmcp?sslmode=disable
BOOTSTRAP_ADMIN=admin
BOOTSTRAP_ADMIN_PASSWORD=Change-Me-Now-2026!
ENCRYPTION_KEY=<gen-key 출력값>

중요: ENCRYPTION_KEY를 잃어버리면 DB에 암호화되어 저장된 비밀값(Keycloak Client Secret, Mattermost 서비스/봇 토큰, 사용자 Mattermost 토큰)을 복구할 수 없습니다. 키는 DB 백업과 분리해서 안전하게 보관하세요.

#2.4 기동

docker compose -f compose.offline.yml up -d
docker compose -f compose.offline.yml ps      # health: healthy 확인
docker logs mmcp | head                        # "mmcp ready" 로그 확인

#2.5 리버스 프록시 뒤에 둘 때

mmcp가 Keycloak과 MCP 클라이언트에 알려 주는 주소(Keycloak redirect_uri, OAuth·MCP 메타데이터, 401 응답의 resource_metadata)는 모두 사용자가 실제로 접속하는 외부 주소여야 합니다. 내부 주소(http://mmcp:8080)가 나가면 Keycloak이 Invalid parameter: redirect_uri 로 로그인을 거부하고, MCP 클라이언트는 자신이 접속한 주소와 메타데이터의 resource가 달라 OAuth를 진행하지 못합니다.

1. 일반 설정 > Public URL에 외부 주소(예: https://mcp.company.co.kr)를 저장하는 것이 가장 확실합니다.
2. Public URL이 비어 있으면 mmcp는 프록시가 보내는 X-Forwarded-Proto, X-Forwarded-Host(필요 시 X-Forwarded-Port) 또는 RFC 7239 Forwarded 헤더로 외부 주소를 계산합니다. Nginx 예:

location / {
    proxy_pass http://mmcp:8080;
    proxy_set_header Host              $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Host  $host;
    proxy_set_header X-Forwarded-Port  $server_port;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_buffering off;   # /api/admin/logs/stream (SSE)
}

3. Keycloak 연동 > 연결 테스트는 mmcp가 보낼 redirect_uri와 로그아웃 후 주소를 Keycloak에 실제로 보내 보고, 등록되지 않았다면 등록해야 할 정확한 값을 알려 줍니다. 오른쪽 가이드 카드의 주소도 서버가 실제로 사용하는 값입니다.

클라이언트 IP(허용목록·호출 한도·감사)와 쿠키 Secure 판단은 보안상 접근 제어 > 프록시 헤더 신뢰를 켠 경우에만 프록시 헤더를 사용합니다.

#2.6 CLI 하위 명령

이미지의 엔트리포인트는 /mmcp이며, 다음 하위 명령을 지원합니다.

#3. 첫 설정 체크리스트

브라우저에서 http://<호스트>:8080에 접속해 부트스트랩 관리자로 로그인합니다. 부트스트랩 관리자에게는 admin, mcp-user, mcp-writer 역할이 부여됩니다.

일반 설정 화면 항목

#4. Keycloak 연동

#4.1 Keycloak 클라이언트 만들기

Realm에 OIDC 클라이언트를 만들고 다음과 같이 설정합니다. (scripts/dev/keycloak-realm.json에 개발용 예시가 있습니다.)

Audience 매퍼는 Keycloak 액세스 토큰을 /mcp에 직접 Bearer로 보내는 경우(사내 AI 포털 등)에 필요합니다. mmcp는 토큰의 aud 또는 azp가 허용 목록(기본: Client ID)에 있어야 받아들이므로, 다른 클라이언트가 발급받은 토큰을 쓰려면 매퍼로 aud에 mmcp Client ID를 넣거나 허용 audience / azp에 해당 값을 추가하세요.

#4.2 mmcp 설정 항목

#4.3 로그인 동작

• 사일런트 SSO: 브라우저 최상위 리다이렉트(prompt=none)로 동작하므로 서드파티 쿠키 차단의 영향을 받지 않습니다. Keycloak 세션이 없으면 조용히 로그인 화면으로 돌아옵니다.
• JIT 사용자 생성: 첫 로그인 시 Keycloak sub를 고정 키로 mmcp 사용자를 만듭니다. 같은 username의 로컬 계정이 이미 있고 Keycloak 연결이 없다면 그 계정에 sub를 연결합니다. 자동 생성이 꺼져 있으면 미등록 사용자는 로그인이 거부됩니다.
• 역할 매핑 (로그인마다 동기화):
  • realm 역할, 이 클라이언트의 client 역할, roles/groups 클레임(그룹은 앞의 / 제거) 중 이름이 mcp-로 시작하는 것은 그대로 mmcp 역할이 됩니다.
  • 관리자로 승격할 Keycloak 역할에 해당하면 admin 역할이 추가됩니다.
  • 기본 역할은 모든 SSO 사용자에게 부여됩니다.
  • Keycloak에서 온 역할(IdP 역할)과 콘솔에서 직접 준 역할(수동 역할)은 합쳐서 적용됩니다.
• 로그인 직후 백그라운드에서 Mattermost 계정 매핑을 미리 수행해 첫 MCP 호출을 빠르게 합니다.

#5. Mattermost 연동

#5.1 권한 모델

• 서비스 토큰은 메시지 조회에 절대 사용되지 않습니다. 시스템 관리자 계정의 개인 액세스 토큰(PAT)을 권장합니다.
• mmcp는 Mattermost 비밀번호를 받거나 저장하지 않습니다. 비밀번호 기반 세션 로그인은 지원하지 않습니다.
• 개인 토큰 자동 발급을 쓰려면 Mattermost 시스템 콘솔에서 개인 액세스 토큰 사용(EnableUserAccessTokens) 을 켜야 합니다.

#5.2 설정 항목

연결 테스트는 system/ping, 서비스 토큰 계정(그리고 system_admin 여부), 봇 토큰 계정을 확인합니다. 서비스 계정이 system_admin이 아니면 사용자 조회만 가능하고 토큰 자동 발급은 불가합니다.

#5.3 발신 계정 선택표

모든 게시물에는 provenance props(mcp, source=mmcp, requested_by, requested_by_mmcp, mmcp_request_id, mmcp_client)가 기록됩니다.

봇 DM 대화방 (bot/auto에서 봇으로 DM을 보낼 때)

#6. 사용자·역할

#6.1 역할

• mcp-* 역할을 하나라도 가지면 기본 조회 권한(mcp-user)이 함께 인정됩니다. 예를 들어 mcp-writer만 가진 사용자도 조회 도구를 쓸 수 있지만, mcp-file·mcp-channel-admin 도구는 해당 역할이 따로 필요합니다. admin, mcp-admin은 모든 역할 검사를 통과합니다.
• 도구 정책에서는 위 역할 외에 mcp-로 시작하는 사용자 정의 역할도 지정할 수 있습니다.

#6.2 사용자 관리

사용자 화면에서 할 수 있는 작업: 로컬 사용자 생성, 수동 역할 변경, 활성/비활성 전환, 비밀번호 재설정, 잠금 해제, 세션 일괄 종료, 삭제.

• 각 사용자의 역할은 수동 역할 ∪ IdP 역할입니다. IdP 역할은 Keycloak 로그인 시 동기화되므로, Keycloak 사용자의 권한은 Keycloak에서 관리하는 것이 원칙입니다.
• 본인 계정과 부트스트랩 관리자는 비활성화·삭제하거나 admin 역할을 제거할 수 없습니다.
• 부트스트랩 관리자는 기동할 때마다 활성 상태와 admin 역할이 보장됩니다(비밀번호는 유지).

#7. 계정 매핑과 충돌 처리

로컬 계정과 Keycloak 자동 연결 규칙: Keycloak 사용자명과 같은 로컬 계정이 있을 때, 그 계정이 비밀번호도 관리자 역할도 없는 SSO 전용 계정이면 첫 로그인 때 자동 연결됩니다. 비밀번호·admin 역할이 있는 계정이나 부트스트랩 관리자는 계정 탈취를 막기 위해 자동 연결하지 않습니다.

DM 정책: DM·그룹 메시지는 DM 전용 도구(mattermost_read_dm, mattermost_send_dm 등)로만 다룰 수 있습니다. 일반 채널 도구에 DM 채널 ID를 넣어도 POLICY_BLOCKED로 거부되므로, DM 도구의 활성화·승인·역할 정책이 항상 적용됩니다.

#7.1 매핑 규칙

1. 최초 탐색: mmcp username(Keycloak 사용자명 클레임, 기본 preferred_username)과 같은 Mattermost username을 서비스 토큰으로 찾습니다. Mattermost 설정의 이메일로 매칭이 켜져 있으면 username이 없을 때 이메일로 찾습니다. 단, 이메일 매칭은 Keycloak이 email_verified=true로 확인한 Keycloak 사용자에게만 적용되며, 사용자가 직접 바꿀 수 있는 로컬 계정 이메일은 절대 사용하지 않습니다. 비활성 계정·봇 계정은 매핑하지 않습니다.
2. 고정: 찾은 뒤에는 Keycloak sub(mmcp 사용자) ↔ Mattermost user_id가 고정됩니다. 이후 username이 같아도 다른 user_id로 바뀌어 연결되지 않습니다.
3. 주기적 재검증: 매핑 검증 캐시 시간이 지나면 매핑된 user_id가 여전히 존재·활성인지, 그리고 username이 여전히 같은 user_id를 가리키는지 확인합니다.
4. 사용자 직접 등록: 사용자가 내 공간 > Mattermost 연결에서 PAT를 등록할 수 있습니다. 토큰 소유자가 로그인 사용자(username 또는 이메일 일치) 또는 관리자가 수동 매핑한 계정과 다르면 거부(IDENTITY_CONFLICT)됩니다.

#7.2 매핑 상태

#7.3 충돌 감지

다음 경우 자동으로 conflict 상태가 되어 해당 사용자의 모든 Mattermost 호출이 차단되고, 감사 로그(mapping / conflict)와 서버 경고 로그가 남습니다.

• 매핑된 Mattermost 계정이 삭제되어 더 이상 존재하지 않음
• 같은 username이 다른 user_id를 가리킴 (계정 삭제 후 재생성, 다른 계정이 그 username으로 변경)
• (서비스 토큰이 없을 때) 저장된 토큰의 소유자 ID가 매핑된 ID와 다름
• 이미 다른 mmcp 사용자와 매핑된 Mattermost 계정에 연결하려 함

자동 경로는 절대 다른 계정으로 재연결하지 않습니다.

#7.4 충돌 해결 절차

1. 계정 매핑 화면에서 충돌 사용자의 사유(last_error)를 확인합니다.
2. Mattermost에서 올바른 계정인지 확인합니다.
3. 다음 중 하나를 수행합니다.
   • 재검증: 관리자가 명시적으로 다시 찾도록 허용합니다. 다른 계정으로 재연결되는 경우 이전 계정의 저장 자격증명은 삭제(mmcp가 자동 발급한 토큰이면 Mattermost에서 폐기)됩니다.
   • 수동 매핑: username이 서로 다른 경우 Mattermost username을 직접 지정합니다. 이전과 다른 계정이면 기존 자격증명을 삭제합니다. 서비스 토큰이 없으면 pending으로 저장되고 사용자가 그 계정의 PAT를 등록하면 완료됩니다.

그 밖의 작업: 미매핑 사용자 자동 매핑(활성 사용자 중 미매핑·pending·not_found 대상, 최대 1000명), 연동 비활성화/활성화, 사용자 토큰 발급·회전, 매핑 삭제(저장 토큰도 삭제).

#8. MCP 도구 정책

#8.1 정책 요소

각 도구마다 다음을 설정합니다.

• 활성화: 꺼진 도구는 목록에 나타나지 않고 호출 시 TOOL_DISABLED
• 모드: auto(즉시 실행) 또는 confirm(2단계 승인). 읽기 도구에는 confirm을 쓸 수 없습니다.
• 역할: 나열된 역할 중 하나라도 가진 사용자만 사용 가능 (없으면 PERMISSION_DENIED)

추가로 다음 조건이 적용됩니다.

• 정책 게이트: 데이터·호출 정책에 따라 도구 자체가 막힐 수 있습니다(아래 표의 "정책 조건").
• 읽기 전용 자격증명: 읽기 전용 API 키나 mcp:read 범위의 OAuth 토큰으로는 쓰기 도구를 쓸 수 없습니다.
• 도구 정책은 첫 기동 때 기본값으로 생성되며, 이후에는 콘솔에서 바꾼 값이 유지됩니다. 화면에서 도구별 최근 24시간 호출·오류 수와 평균 지연 시간도 확인할 수 있습니다.

#8.2 2단계 승인 (confirm 모드)

1. 첫 호출(confirm_token 없음) → APPROVAL_REQUIRED 오류와 함께 미리보기(preview), confirm_token, 만료 시각을 반환합니다.
2. AI 클라이언트가 미리보기를 사용자에게 보여 주고, 사용자가 동의하면 같은 인자에 confirm_token을 더해 다시 호출합니다.
3. 사용자는 내 공간 > 승인 요청에서 대기 중인 요청을 승인·거절할 수도 있습니다.

#8.3 도구 목록과 기본값 (28종)

• 쓰기 도구는 mattermost_add_reaction을 제외하고 모두 기본 confirm 모드입니다.
• 위험 도구(mattermost_delete_post, mattermost_archive_channel)는 기본 비활성입니다.
• mattermost_upload_dm_file은 mcp-writer 또는 mcp-file 중 하나만 있어도 사용할 수 있습니다.

호환 별칭 (데이터·호출 정책에서 켰을 때만 노출, 정책은 원본 도구를 따름)

MCP 리소스(mattermost://me, teams, channels, unread, channels/{channel_id}, threads/{post_id}, users/{username}, dms/{username})와 프롬프트(summarize_channel, find_decisions, daily_digest, draft_dm)도 제공되며, 리소스 읽기는 해당 도구의 정책·한도·감사를 그대로 거칩니다.

#9. 데이터·호출 정책

Mattermost 권한 위에 한 겹 더 거는 정책입니다. 사용자가 Mattermost에서 볼 수 있더라도 여기서 끄면 MCP로는 접근할 수 없습니다(POLICY_BLOCKED).

#9.1 데이터 접근 범위

#9.2 결과·감사

#9.3 사용자별 분당 호출 한도

사용자 단위, 버킷별 1분 창으로 계산합니다. 초과 시 RATE_LIMITED와 재시도 대기 시간을 반환합니다.

#9.4 MCP OAuth

게이트웨이 모드의 동작:

• 인가 코드 + PKCE S256 필수, 공개 클라이언트(token_endpoint_auth_method=none)만 발급
• redirect URI는 https, 루프백 http(포트 무관), 네이티브 앱용 사설 스킴만 허용
• 회전형 리프레시 토큰: 사용할 때마다 새 토큰을 발급하고 이전 토큰은 폐기. 폐기된 리프레시 토큰이 재사용되면 탈취로 간주해 그 토큰 계열 전체를 폐기하고 감사 로그(oauth / refresh_reuse, TOKEN_REUSE)를 남깁니다.
• 범위: mcp(전체) / mcp:read(읽기 전용)

#9.5 API 키·키 회전 정책

개인 API 키(mmcp_pk_ 접두사)는 사용자가 내 공간 > 내 API 키에서 발급합니다. 읽기 전용 옵션이 있고, 회전 시 이전 키를 유예 시간(최대 7일) 동안 계속 쓸 수 있게 할 수 있습니다.

#10. 클라이언트·세션

#10.1 MCP 엔드포인트와 인증

• 엔드포인트: {Public URL}/mcp (Streamable HTTP, POST/DELETE. 서버 발신 SSE 스트림은 제공하지 않음)
• 지원 프로토콜 버전: 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05
• 인증 실패 시 401과 WWW-Authenticate: Bearer ... resource_metadata="{Public URL}/.well-known/oauth-protected-resource/mcp"를 반환합니다.

#10.2 화면

• OAuth 클라이언트 탭: 동적 등록(DCR) 클라이언트 목록, 사용자 수, 활성 토큰 수, 마지막 사용. 허용 스위치로 차단하면 해당 클라이언트의 토큰이 즉시 무효가 되고, 삭제하면 클라이언트와 발급 토큰이 함께 삭제됩니다.
• MCP 세션 탭: 클라이언트 이름·버전, 인증 방식, 프로토콜, IP, 호출 수. 세션을 종료하면 클라이언트는 다시 initialize해야 합니다. 24시간 활동이 없으면 자동 종료, 30일 지난 세션은 삭제됩니다.

#10.3 웹 세션과 API 키

웹 세션	API 키 현황

• 웹 세션: 콘솔 로그인 세션(인증 방식, IP, User-Agent)을 확인하고 강제 종료합니다. 세션 유효시간은 접근 제어에서 설정합니다(기본 12시간).
• API 키 현황: 전체 사용자의 API 키 상태(활성/만료/폐기, 회전 주기 초과 여부, 마지막 사용 IP)를 보고 폐기할 수 있습니다.

#11. 키 관리와 회전

#11.1 봉투 암호화 구조

ENCRYPTION_KEY (마스터 키, 환경변수 — DB에 저장되지 않음)
 ├─ 시스템 데이터 키 (AES-256-GCM)  → Keycloak Client Secret, Mattermost 서비스/봇 토큰
 └─ 사용자별 데이터 키 (AES-256-GCM) → 사용자의 Mattermost 토큰

• 데이터 키는 마스터 키로 감싸서(wrap) DB에 저장되며, 감쌀 때 키 ID·소유자를 AAD로 묶어 다른 행으로 옮겨 쓸 수 없습니다.
• 각 암호문도 용도별 AAD(예: 사용자 ID)에 묶입니다.
• API 키·OAuth 토큰은 원문이 아닌 해시로만 저장됩니다.

화면 상단 지표: 주 마스터 키, 재래핑 필요 데이터 키, 회전 주기 초과 사용자 키, 자동 발급 Mattermost 토큰 수.

#11.2 회전 작업

#11.3 런북: 마스터 키 회전 (무중단 절차)

# 1) 새 키 생성
docker run --rm mmcp:v1.0.1 gen-key

# 2) .env에서 새 키를 앞에, 이전 키를 뒤에 두고 재시작
#    ENCRYPTION_KEY="<새 키>,<이전 키>"
docker compose -f compose.offline.yml up -d

# 3) 관리 콘솔 > 키 관리 > 마스터 키 > "재래핑" 실행

# 4) "재래핑 필요 데이터 키"가 0인지 확인

# 5) .env에서 이전 키를 제거하고 재시작
#    ENCRYPTION_KEY="<새 키>"
docker compose -f compose.offline.yml up -d

주의:

• 4단계 확인 전에 이전 키를 제거하면 해당 데이터 키로 암호화된 값을 복호화할 수 없습니다.
• 마스터 키 표에서 상태가 없음인 키 ID가 보이면, 그 키로 감싼 데이터 키가 남아 있는데 ENCRYPTION_KEY에 그 키가 없다는 뜻입니다.
• 재시작 직전에 시작된 Keycloak 로그인 진행 중 요청은 실패할 수 있으니(로그인 상태 쿠키 서명이 주 키에서 파생) 사용량이 적은 시간에 진행하세요.

#12. 접근 제어

• IP 항목은 단일 IP(자동으로 /32, /128)나 CIDR로 입력합니다.
• 관리자 허용목록을 잘못 지정하면 관리 콘솔에 접근할 수 없게 됩니다. 저장 전 현재 접속 IP가 포함되는지 확인하세요.
• 상태 변경 API는 X-Requested-With: mmcp 헤더를 요구해 CSRF를 막습니다.

#13. 감사 로그·승인 이력

#13.1 감사 로그

• 결과 값: success / failure / denied / pending
• 범주, 결과, 행위자, 기간, 자유 검색(작업·대상·오류 코드·클라이언트·Mattermost 사용자·요청 ID)으로 필터링
• CSV 내보내기: 현재 필터 기준 최대 50,000행, Excel용 BOM 포함. =, +, -, @ 등으로 시작하는 값에는 '를 붙여 스프레드시트 수식 주입을 막습니다.
• 보존 기간: 일반 설정의 감사 로그 보존 기간(기본 180일)이 지난 이벤트는 10분 주기 정리 작업에서 삭제됩니다.
• 모든 HTTP 응답의 요청 ID(X-Request-Id)로 감사 이벤트와 서버 로그를 서로 찾아볼 수 있습니다.

#13.2 승인 이력

쓰기 도구의 승인 요청을 사용자·도구·미리보기 요약·상태(pending / approved / rejected / executed / expired)·클라이언트 별로 확인합니다. 만료된 대기 요청은 정리 작업에서 expired로 바뀝니다.

#14. 서버 로그

• 서버는 JSON 구조화 로그를 표준 출력(docker logs mmcp)으로 내보내고, 최근 5,000건을 메모리에 보관해 콘솔에 보여 줍니다.
• 실시간 tail: SSE 스트림으로 새 로그를 즉시 표시합니다. 리버스 프록시에서는 버퍼링을 끄세요(서버가 X-Accel-Buffering: no를 보냄).
• 레벨 필터, 텍스트 검색(메시지·속성)
• 다운로드: 메모리 버퍼 전체를 NDJSON으로 저장
• 로그 레벨 변경: debug / info / warn / error. 변경 즉시 적용되며 일반 설정에 저장되어 재기동 후에도 유지됩니다.
• 장기 보관이 필요하면 Docker 로깅 드라이버나 로그 수집기로 표준 출력을 수집하세요.

#15. 백업·복원·업그레이드

#15.1 설정 백업 (콘솔)

• 내보내기: 4개 설정 구역(general, keycloak, mattermost, mcp)과 도구 정책을 mmcp-config/v1 형식 JSON(mmcp-config-<시각>.json)으로 저장합니다. 비밀값은 포함되지 않습니다.
• 가져오기: 검증을 거쳐 구역별로 저장합니다. 백업 파일의 비어 있는 비밀값은 "변경 없음"으로 처리되어 기존 비밀값이 유지됩니다. 새 설치에 가져온 경우 Client Secret, 서비스/봇 토큰은 다시 입력하세요.
• 설정 백업에는 사용자, 매핑, 토큰, API 키, 감사 로그가 들어 있지 않습니다. 전체 백업은 DB 덤프로 하세요.

#15.2 데이터베이스 백업과 복원

# 백업 (예시)
pg_dump "$POSTGRES_DSN" -Fc -f mmcp-$(date +%Y%m%d).dump

# 복원 (예시: 빈 DB에)
pg_restore -d "$POSTGRES_DSN" --clean --if-exists mmcp-YYYYMMDD.dump

• DB에는 마스터 키로 감싼 데이터 키만 있으므로, 복원한 DB를 쓰려면 백업 당시와 같은 ENCRYPTION_KEY (또는 그 키를 포함한 키 목록)가 필요합니다.
• DB 덤프와 ENCRYPTION_KEY는 서로 다른 위치에 보관하세요.

#15.3 업그레이드

1. 설정 내보내기와 DB 덤프를 받습니다.
2. 새 릴리스 아카이브를 반입해 sha256sum 값을 릴리스 노트와 비교하고 docker load 합니다.
3. compose.offline.yml의 image: 태그(현재 mmcp:v1.0.1)를 새 태그로 바꿉니다.
4. docker compose -f compose.offline.yml up -d — 시작 시 DB 마이그레이션이 자동 적용되며 로그에 migrations applied가 남습니다.
5. 시스템 정보 화면에서 버전(현재 v1.0.1에서 바뀌었는지)과 마이그레이션을 확인합니다.

#15.4 비상 복구: 관리자 비밀번호 분실

부트스트랩 관리자의 비밀번호는 재기동해도 바뀌지 않습니다. 분실·잠금 시:

# .env의 BOOTSTRAP_ADMIN_PASSWORD를 새 값으로 바꾼 뒤
docker run --rm --env-file .env mmcp:v1.0.1 reset-admin-password
# → "password reset for admin"

비밀번호 재설정과 함께 잠금 해제·활성화가 이루어집니다. 컨테이너가 DB에 접근할 수 있는 네트워크에서 실행해야 합니다(필요하면 --network 지정).

#16. 모니터링 엔드포인트

주요 메트릭:

권장 경보: /api/ready 503 지속, mmcp_tool_calls_total의 실패·거부 비율 급증, 감사 로그의 IDENTITY_CONFLICT·TOKEN_REUSE 발생.

#17. 문제 해결

#17.1 설치·접속

#17.2 Keycloak

#17.3 LLM 클라이언트가 받는 오류 코드

HTTP 수준 오류: IP_DENIED(IP 허용목록), ORIGIN_DENIED(CORS Origin), SESSION_NOT_FOUND(종료된 MCP 세션 — 클라이언트 재연결 필요).

#17.4 Mattermost 연동

#18. 보안 체크리스트

배포

• ENCRYPTION_KEY를 gen-key로 생성하고 DB 백업과 분리 보관
• BOOTSTRAP_ADMIN_PASSWORD를 강력한 값으로 설정하고 첫 로그인 후 비밀번호 변경
• compose.offline.yml의 읽기 전용 루트 FS, no-new-privileges, cap_drop: ALL 유지
• TLS 종단 리버스 프록시 뒤에 배치하고 Public URL을 https://로 설정
• 프록시 사용 시에만 프록시 헤더 신뢰 켜기
• PostgreSQL 접속에 TLS(sslmode)와 최소 권한 계정 사용

인증·접근

• Keycloak 클라이언트: confidential, Standard flow + PKCE S256, Direct access grants OFF, 짧은 액세스 토큰 수명
• Keycloak SSO 안정화 후 로컬 계정 로그인 끄기 (부트스트랩 관리자만 비상용 유지)
• 관리 콘솔·메트릭 IP 허용목록 설정 (현재 IP 포함 확인)
• 필요 시 MCP IP 허용목록 설정, CORS Origin은 필요한 것만 등록 (* 지양)
• admin / mcp-admin 역할 보유자 최소화, 정기 점검
• 테스트 전용 TLS 검증 생략 옵션이 꺼져 있는지 확인

데이터·도구

• DM 검색, 첨부 파일 내용 조회는 필요할 때만 켜기
• 위험 도구(mattermost_delete_post, mattermost_archive_channel)는 비활성 유지
• 쓰기 도구의 confirm 모드 유지, 승인 유효시간 최소화
• 민감 환경에서는 콘솔 승인 필수(엄격 모드) 켜기 — 프롬프트 인젝션으로 AI가 스스로 승인하는 것을 차단
• 리버스 프록시 뒤라면 프록시 헤더 신뢰를 켜고, 꺼져 있을 때는 X-Forwarded-* 헤더가 무시됨을 확인 (X-Forwarded-For는 가장 오른쪽 값만 사용)
• 일반 설정 > 표시 시간대를 조직 시간대(기본 Asia/Seoul)로 확인
• 조회 결과 신뢰불가 표시 유지
• 감사 로그 본문 저장은 규정상 필요할 때만 켜기
• 서비스 토큰은 디렉터리 조회·토큰 발급 전용 계정으로 분리

운영

• API 키 만료일 필수·최대 유효기간 설정 검토
• 회전 주기 초과 사용자 키·API 키 정기 회전, 자동 발급 토큰 정기 일괄 회전
• 마스터 키 정기 회전 (11.3 런북)
• 감사 로그의 IDENTITY_CONFLICT, TOKEN_REUSE, 반복 denied 모니터링
• 미사용 OAuth 클라이언트 차단·삭제, 오래된 웹 세션 정리
• 설정 내보내기 + DB 덤프 정기 백업과 복원 리허설