MCP 툴 호출 기록

Claude Desktop, Claude Code 같은 외부 클라이언트가 MCP 서버를 통해 실행한 모든 도구 호출을 기록으로 남기는 기능입니다. 누가 어떤 도구를 어떤 값으로 호출했고 성공했는지 실패했는지를 IntelliConnect 관리 화면 한 곳에서 확인합니다.

여러 MCP 서버(IntelliDesk MCP, OData Bridge, Query Bridge)의 기록이 같은 화면에 모입니다.

접근 권한

이 화면과 아래 설정은 서비스 운영자만 다룹니다. Tenant Admin은 기록 조회가 필요할 때 Admin에게 요청합니다.

IntelliConnect 관리 콘솔 사용

IntelliConnect는 기존 IntelliSSO의 새 이름이며 IntelliDesk와 별도 앱으로 실행됩니다. 이름 변경 후에도 기존 인증 주소와 연동 설정을 그대로 사용합니다. 개발 환경에서는 intellidesk와 같은 상위 폴더의 intelli-sso에서 설치·실행하며, 운영 환경에서는 운영자가 안내한 SSO 주소로 접속합니다.

1. 관리 콘솔 첫 화면에서 관리자 비밀키를 입력합니다. 서버가 키를 검증한 뒤 관리 메뉴가 열립니다. 이 키는 사용자 계정 비밀번호와 다릅니다.
2. 대시보드의 SAML·OAuth 카드에서 프로토콜별 활성 연결 수와 인증 이벤트를 확인합니다. 각 카드에서 앱 관리, 설정, 해당 프로토콜 로그로 이동할 수 있습니다.
3. SAML 2.0 영역의 SAP 시스템, API 키 앱, SAML 설정에서 SAP 연결과 API 키별 허용 시스템을 관리합니다. OAuth 2.1 영역의 OAuth 앱, OAuth 설정에서는 OAuth 앱과 토큰 정책을 관리합니다. 사용자 계정은 사용자 메뉴에서 관리합니다.
4. SSO 로그는 프로토콜·결과·이메일·기간으로, MCP 툴 호출은 서버·도구·이메일·상태로 조회합니다. 더 보기로 다음 기록을 확인합니다.
5. 최신 데이터가 필요하면 새로고침을 누릅니다. 작업이 끝나면 로그아웃합니다.

관리자 키는 브라우저 저장소에 저장되지 않으므로 새로고침하거나 창을 다시 열면 다시 로그인해야 합니다. 잘못된 키나 서버 연결 실패는 로그인 화면에 표시됩니다. 모바일에서는 메뉴를 좌우로 스크롤하고, 표도 표 영역 안에서 좌우로 움직일 수 있습니다. 입력 창은 Esc로 닫을 수 있습니다.

일반 사용자는 /saml/login에서 접속할 시스템을 선택하고 이메일과 비밀번호로 로그인합니다. 계정 만들기에서 이름과 이메일, 비밀번호를 등록할 수 있습니다. 모바일에서도 같은 화면을 이용하며, 표시 버튼으로 비밀번호 입력값을 확인할 수 있습니다.

가입 화면은 비밀번호의 6자 이상 조건과 확인값의 일치 여부를 안내합니다. 잘못 입력한 항목 아래에 오류가 표시되고, 제출하면 첫 오류 항목으로 이동합니다. 가입 실패 시 이름과 이메일은 유지되지만 비밀번호는 다시 입력해야 합니다. 가입이 끝나면 이메일이 채워진 로그인 화면으로 이동합니다. 로그인 실패 시에도 이메일과 선택한 시스템이 유지됩니다.

비밀번호를 잊었거나 접속할 시스템이 보이지 않으면 **로그인에 도움이 필요하신가요?**를 펼쳐 안내를 확인하고 조직 관리자에게 문의합니다. 연결된 시스템이 없으면 로그인 버튼이 비활성화됩니다.

외부 앱의 OAuth 연결 승인 화면에서는 요청한 앱 이름, 권한 설명, 연결 완료 후 이동할 주소를 확인할 수 있습니다. 로그인하고 연결 승인을 누르면 해당 앱에 표시된 권한을 허용합니다. 알 수 없는 앱이면 창을 닫습니다.

SAML 설정

SAP 시스템에서 SP 메타데이터 XML을 가져오거나 Entity ID·ACS URL·Target URL·Relay State를 입력합니다. 로그인 허용을 끄면 해당 시스템의 SAML 연결을 중지합니다. API 키 앱에서는 앱별 허용 시스템을 선택하고 키 인증을 중지하거나 키를 재발급할 수 있습니다. 시스템을 선택하지 않으면 접근을 허용하지 않습니다. 모든 SAML 시스템 허용을 선택하면 이후 등록하는 시스템도 포함됩니다.

SAML 설정에서 IdP Entity ID, 로그인·로그아웃 URL, Assertion 유효 시간(30~600초)을 저장하면 즉시 적용됩니다. 연결 식별자나 URL을 변경한 경우 SAP의 신뢰 설정도 갱신해야 합니다. 공개 인증서의 만료일·지문을 확인하고 IdP 메타데이터를 다운로드할 수 있습니다. 개인 키와 인증서 교체는 서버 배포 설정에서 관리합니다.

OAuth 앱과 정책

OAuth 앱에서 이름, Client ID, 앱 유형, 허용 리디렉션 URI와 권한(Scope)을 등록합니다. Client ID를 비우면 자동 생성됩니다. 공개 앱은 PKCE를 사용하고, 서버 앱은 PKCE와 client_secret_post를 함께 사용합니다. 서버 앱 비밀키는 발급 직후 한 번만 표시되므로 안전하게 보관합니다. 등록 후 앱 유형을 바꾸려면 새 앱을 등록합니다.

리디렉션 URI는 한 줄에 하나씩 입력합니다. HTTPS와 로컬 개발 주소, 허용되는 앱 전용 스킴을 사용할 수 있으며 와일드카드는 허용되지 않습니다. 목록에서 앱을 검색하거나 활성·중지 상태로 필터링할 수 있습니다. 관리자가 등록한 앱과 동적으로 등록된 앱을 함께 표시합니다.

앱 중지, 리디렉션 URI·권한 변경, 비밀키 재발급은 기존 인증 코드와 토큰 갱신을 무효화합니다. 이미 발급한 액세스 토큰은 만료 시점까지 유효할 수 있습니다. 환경변수로 등록한 앱을 삭제하면 재시작 시 다시 생성될 수 있으므로 영구 제거할 때 해당 환경 설정도 정리합니다.

OAuth 설정에서는 액세스 토큰 수명(60~86,400초), 리프레시 토큰 수명(1~90일), 인증 코드 수명(30~600초)을 지정합니다. 리프레시 토큰 수명은 회전 시점부터 계산합니다. 저장 후 새로 발급하는 토큰에 적용되며 기존 토큰의 만료 시각은 바뀌지 않습니다. 동적 앱 등록을 끄면 신규 자동 등록만 차단하며 기존 앱은 유지합니다. 동적 등록 허용 권한은 필요한 최소 범위로 지정합니다.

Issuer·인증·토큰·Discovery·JWKS 주소는 앱 연결 정보에서 복사합니다. Issuer는 서버의 OAUTH_BASE_URL로 고정되며 변경할 때 연결 앱의 신뢰 설정도 함께 갱신해야 합니다. UI에서 저장한 프로토콜 설정은 DB에 보존되고 환경변수의 초기값보다 우선합니다.

프로토콜별 엔드포인트

구분	메서드	경로	용도
SAML	GET, POST	/saml/login	사용자 로그인 및 SP 요청 처리
SAML	GET, POST	/saml/register	사용자 계정 생성
SAML	GET	/saml/logout	로그아웃 화면
SAML	GET	/saml/metadata	IdP 메타데이터
SAML	GET	/saml/systems	API 키로 시스템 목록 조회
SAML	POST	/saml/launch, /saml/launch-json	API 키로 SAML 응답 발급
OAuth	GET, POST	/oauth/authorize	로그인 및 앱 연결 승인
OAuth	POST	/oauth/token, /oauth/revoke	토큰 발급·폐기
OAuth	POST	/oauth/register	OAuth 클라이언트 등록
OAuth	GET	/oauth/jwks, /oauth/metadata	공개 키 및 서버 메타데이터

OAuth 자동 탐색용 /.well-known/oauth-authorization-server도 RFC 8414에 따라 유지합니다. /oauth/register는 사용자 회원가입이 아니라 앱 등록 API입니다.

기존 /api/v1/sso/*는 같은 인증·권한 검사와 로그인 시도 제한을 사용하는 호환 경로입니다. POST를 리디렉션하지 않으므로 기존 API 키와 요청 본문을 그대로 처리합니다. 신규 연동의 SAP_SSO_API_URL은 https://<인증서버>/saml로 설정합니다.

SAML Entity ID와 OAuth Issuer는 신뢰 식별자이므로 URL 정리만으로 바꾸지 않습니다. 환경변수나 관리 화면에 저장된 로그인·로그아웃 URL도 자동으로 덮어쓰지 않습니다. 기존 설치에서 새 주소를 메타데이터에 표시하려면 SAML 설정의 로그인·로그아웃 URL을 /saml/login, /saml/logout으로 저장하고 SAP의 메타데이터를 갱신합니다. Entity ID를 따로 지정하지 않은 기존 설치는 종전 기본 식별자(/api/v1/sso/metadata)를 유지하며, 메타데이터 다운로드 주소는 /saml/metadata를 사용합니다.

분리된 서비스 운영

IntelliDesk의 배포 스크립트는 SSO를 배포하거나 재시작하지 않습니다. SSO 저장소의 README와 PM2 설정을 사용합니다. 이전할 때 기존 DB, 인증서와 환경 파일을 보존합니다. MCP 서버의 OAUTH_PUBLIC_KEY_PATH와 IntelliDesk 서버의 SSO_LOG_DIR는 실제 배치 경로를 가리켜야 합니다.

기록되는 항목

구분	내용
사용자	이메일, OAuth 클라이언트, 테넌트, SAP 시스템 ID, 접속 IP
도구	MCP 서버 이름, 도구 이름
파라미터	호출에 사용한 값
결과	응답 크기와 앞부분 요약
실패	성공 여부, 실패 사유, 소요 시간

기록에는 두 가지 안전장치가 있습니다.

• 이름에 password, secret, token, cookie, apikey, credential, authorization이 포함된 파라미터는 값이 [redacted]로 가려집니다.
• 결과는 전문이 아니라 크기와 앞부분 요약만 남습니다. ABAP 소스처럼 큰 응답이 기록을 채우지 않도록 하기 위해서입니다. 조회한 데이터 자체를 이 화면에서 다시 볼 수는 없습니다.

설정

설정하지 않으면 기능이 꺼진 상태로 동작합니다. 도구 호출은 정상적으로 처리되고 기록만 남지 않습니다.

1. 공유 키 준비

IntelliConnect와 각 MCP 서버가 같은 값을 나눠 갖습니다. 충분히 긴 임의 문자열을 하나 만듭니다.

openssl rand -hex 32

2. IntelliConnect 설정

독립 SSO 저장소의 service/.env.production에 다음을 추가합니다.

MCP_AUDIT_API_KEY=1단계에서_만든_값
MCP_LOG_RETENTION_DAYS=30

MCP_AUDIT_API_KEY가 없으면 수집 엔드포인트가 아예 열리지 않습니다. 인증 없이 열어 두는 것보다 꺼진 상태가 안전하기 때문입니다.

MCP_LOG_RETENTION_DAYS는 기록 보존 기간이며 생략하면 30일입니다. 도구 호출은 로그인 기록보다 훨씬 잦으므로 접근 로그(SSO_LOG_RETENTION_DAYS, 기본 90일)와 따로 관리합니다.

3. 각 MCP 서버 설정

세 서버의 .env.production에 같은 두 줄을 추가합니다. MCP_AUDIT_API_KEY는 2단계와 같은 값이어야 합니다.

MCP_AUDIT_URL=https://sso.liteway.cc/api/v1/mcp-logs
MCP_AUDIT_API_KEY=1단계에서_만든_값

MCP 서버	설정 파일
IntelliDesk MCP	mcp-server/.env.production
OData Bridge	odata-bridge/mcp-unified/.env.production
Query Bridge	query-bridge/.env.production

4. 재시작

설정은 기동할 때 한 번 읽습니다. IntelliConnect와 설정을 바꾼 MCP 서버를 재시작합니다.

동작 확인

기동 로그 확인

각 서버의 기동 로그에서 감사 기능이 켜졌는지 확인합니다.

서버	정상일 때 로그
IntelliConnect	MCP audit log collection enabled
MCP 서버	MCP audit enabled (endpoint 값이 함께 표시됩니다)

disabled로 나오면 해당 서버의 MCP_AUDIT_URL 또는 MCP_AUDIT_API_KEY가 비어 있습니다.

실제 호출로 확인

1. Claude Desktop 등 MCP 클라이언트로 연결해 도구를 한 번 실행합니다.
2. 몇 초 기다립니다. 기록은 즉시 보내지 않고 모아서 보냅니다.
3. IntelliConnect 관리 화면의 MCP 툴 호출 탭을 새로 고칩니다.
4. 방금 실행한 도구가 목록 맨 위에 나타나는지 확인합니다.

화면에서 조회

IntelliConnect 관리 화면에 로그인한 뒤 🛠 MCP 툴 호출 탭을 엽니다. 접근 로그를 보는 📋 SSO 로그 탭과는 별도입니다. 도구 호출이 로그인 기록보다 훨씬 잦아 한곳에 섞으면 접근 로그가 묻히기 때문에 나눠 두었습니다.

상단 입력란으로 걸러서 봅니다.

필터	사용하는 상황
서버	특정 MCP 서버의 호출만 볼 때
도구	반복 실패하는 도구를 찾을 때
이메일	특정 사용자의 SAP 조회 이력을 추적할 때
상태	실패한 호출만 모아 볼 때

파라미터와 결과 칸은 길면 잘려 보입니다. 마우스를 올리면 전체 내용이 표시됩니다.

문제 해결

기록이 전혀 쌓이지 않습니다

1. MCP 서버 기동 로그가 MCP audit enabled인지 확인합니다. disabled면 그 서버의 환경 변수가 비어 있습니다.
2. IntelliConnect 기동 로그가 MCP audit log collection enabled인지 확인합니다. MCP_AUDIT_API_KEY not set 경고가 보이면 IntelliConnect 쪽 설정이 빠진 것입니다.
3. MCP 서버 로그에 MCP audit send failed가 있는지 확인합니다. 이 경고에 담긴 사유가 원인입니다.

MCP audit send failed에 403이 찍힙니다

IntelliConnect와 MCP 서버의 MCP_AUDIT_API_KEY가 서로 다릅니다. 양쪽을 같은 값으로 맞추고 재시작합니다.

일부 서버의 기록만 보입니다

기록이 안 보이는 서버만 설정이 빠졌거나 재시작되지 않은 경우입니다. 해당 서버의 기동 로그부터 확인합니다.

실패한 호출이 성공으로 기록됩니다

도구가 오류를 MCP 규격의 실패(isError)가 아니라 응답 본문에만 담아 돌려주는 경우입니다. 기록은 MCP 규격을 따르므로 성공으로 남습니다. 결과 요약에 오류 메시지가 보이면 이 경우이며, 해당 도구를 수정해야 합니다.

기록이 유실될 수 있는 경우

기록은 도구 호출을 지연시키지 않도록 모아서 따로 보냅니다. 그래서 IntelliConnect가 내려가 있거나 MCP 서버가 강제 종료되면 그 구간의 기록이 남지 않을 수 있습니다. 도구 호출 자체는 어떤 경우에도 영향을 받지 않습니다.