MCP로 앱 조회하기

외부 AI 클라이언트에서 Intellidesk MCP 서버에 연결하면 앱에 저장된 체계도, 흐름도, 문서, 비즈니스 인사이트, SAP 분석 결과를 조회할 수 있습니다. 앱에서 사용하는 사용자 권한과 테넌트 범위가 적용됩니다.

서비스 상태와 접속 정보

최고 관리자는 설정 → MCP 서비스(/app/admin/mcp)에서 다음 정보를 확인합니다.

• MCP 서버에는 현재 설정된 서비스의 응답 여부, 응답 시간, 등록된 도구 수와 앱 서버의 연결 주소가 표시됩니다.
• 앱 인증 연결은 현재 로그인한 사용자 JWT와 테넌트로 MCP 도구 목록을 조회한 결과입니다. 인증 거부와 연결 실패를 구분하며 AI 에이전트 서비스의 응답 여부도 표시합니다.
• 외부 클라이언트 접속에는 실제 MCP 메타데이터의 공개 주소, 인증 서버, 보호 리소스 메타데이터와 OAuth 범위가 표시됩니다. 공개 주소의 인증 안내와 메타데이터 경로가 정상인지 함께 점검합니다.
• 주소 복사 또는 설정 예시 복사로 접속 정보를 복사합니다. JSON은 HTTP 연결 설정 예시이므로 사용하는 클라이언트의 형식에 맞춰 등록합니다.
• 새로고침을 누르면 다시 점검합니다. 실패한 점검에서 이전 성공 상태를 계속 표시하지 않습니다.

이 화면은 조회 전용이며 현재 DB의 최고 관리자 역할을 확인합니다. 비밀키와 사용자 토큰은 표시하지 않습니다. MCP는 세션을 유지하지 않으므로 연결 상태는 마지막 점검 시점의 결과입니다. 도구 목록 조회 성공만으로 SAP 시스템의 접속 성공을 판단할 수 없습니다. 표시된 목록은 INTELLIDESK 경로의 도구이며 챗봇과 각 에이전트는 별도의 허용 목록을 사용합니다. 챗봇에는 SAP 도구 10개와 문서 도구 2개를 제공하며 테스트용 날씨 도구는 제공하지 않습니다.

연결

업무에 따라 다음 주소로 연결합니다. 기존 혼합 /mcp 경로는 제공하지 않습니다.

도구 묶음	운영 주소	조건
INTELLIDESK	https://mcp.liteway.cc/intellidesk/mcp	앱 사용자 인증과 권한. SAP 연결 불필요.
SAP 실시간 도구	https://mcp.liteway.cc/sap/mcp	SAP 시스템과 Basic 또는 SAML 연결.

개발 표준·제품 개발 가이드·저장된 SAP 분석 조회는 INTELLIDESK 도구입니다. SAP 시스템이 없거나 SAP 인증에 실패해도 앱 조회 도구는 유지됩니다.

개발 환경의 기본 MCP 포트는 11000입니다. OAuth를 지원하는 클라이언트에서는 운영자가 설정한 인증 서버로 로그인합니다. 앱에도 같은 이메일의 활성 사용자가 등록되어 있어야 합니다.

내부 앱·에이전트에서 앱 JWT를 사용하는 연결은 X-Internal-API-Key, Authorization: Bearer <사용자 JWT> 또는 x-auth-token, x-tenant-id를 전달합니다. MCP가 앱 서버에 토큰 검증을 위임하므로 JWT 비밀키를 공유하지 않습니다. 외부 클라이언트는 OAuth로 연결합니다. 인증 토큰이나 테넌트를 AI 도구의 입력값으로 전달하지 않습니다. 내부 API 키만으로는 새 앱 조회 도구를 사용할 수 없습니다.

OAuth 연결에서는 커스텀 헤더의 X-Internal-API-Key를 제거하고 다시 로그인합니다. 내부 키로 연결이 먼저 성공하면 클라이언트가 OAuth 로그인을 시작하지 않을 수 있습니다. x-tenant-id는 조회할 테넌트로 지정합니다.

OAuth 토큰의 이메일과 같은 사용자를 해당 테넌트에서 찾고, 활성 상태와 로그인 허용 여부를 확인한 뒤 앱 사용자 토큰을 발급합니다. 사용자는 자동으로 생성하지 않습니다.

운영자는 앱 서버에 EXTERNAL_JWT_PUBLIC_KEY_PATH를 설정합니다. MCP가 사용하는 OAuth 공개키 또는 인증서와 같은 서명키여야 합니다. EXTERNAL_JWT_ISSUER는 인증 서버의 발급자 주소, EXTERNAL_JWT_AUDIENCE는 클라이언트에 등록한 MCP 주소와 일치시킵니다. 두 설정은 필수입니다. MCP의 OAUTH_RESOURCE_URL은 INTELLIDESK 공개 주소로 지정합니다. SAP 경로의 OAuth resource와 토큰 audience는 같은 호스트의 /sap/mcp이며 두 경로의 토큰을 서로 사용할 수 없습니다. 앱 서버의 EXTERNAL_JWT_AUDIENCE는 앱 토큰 교환을 위한 /intellidesk/mcp 주소입니다. 개발 주소는 http://localhost:11000/intellidesk/mcp, 운영 주소는 https://mcp.liteway.cc/intellidesk/mcp입니다. 개발 인증 서버는 http://localhost:9000, 운영 인증 서버는 https://sso.liteway.cc입니다. 클라이언트와 서버 설정은 같은 환경을 사용해야 합니다. 앱 서버에서 파일을 읽을 수 있어야 하며 설정 변경 후 서버를 재시작합니다. 기존 대칭키 외부 로그인용 EXTERNAL_JWT_SECRET은 앱 서버에서만 유지할 수 있습니다. 앱 JWT용 JWT_SECRET은 MCP에 복사하지 않습니다. 서명을 검증할 수 없는 외부 토큰은 거부합니다. 이전 토큰에 대상 서비스 정보가 없으면 연결을 해제하고 다시 OAuth로 로그인합니다.

로그인 화면 전에 DCR 404가 표시되는 경우

클라이언트 등록 요청 경로를 찾지 못한 오류입니다. 운영자는 MCP의 WWW-Authenticate가 안내하는 메타데이터 주소와 인증 서버의 registration_endpoint를 확인합니다. localhost 개발 연결은 http://localhost:11000/intellidesk/mcp를 사용하고 인증 서버의 등록 주소는 http://localhost:9000/oauth/register여야 합니다. 개발 설정에 운영 MCP 주소를 넣지 않습니다. 설정 변경 후 앱 서버와 MCP를 재시작하고 클라이언트를 다시 연결합니다. 운영 연결은 리버스 프록시가 보호 리소스 메타데이터 경로도 전달해야 합니다.

운영 Nginx는 두 endpoint와 두 metadata 경로를 전체 경로 그대로 MCP에 전달해야 합니다. 기존 /intellidesk/ 접두사를 제거하는 설정은 교체합니다. HTTPS 서버 블록에 다음 설정을 적용하고 sudo nginx -t가 통과하면 sudo systemctl reload nginx를 실행합니다.

location ~ ^/(intellidesk/mcp|sap/mcp|\.well-known/oauth-protected-resource/(intellidesk|sap)/mcp)$ {
    proxy_pass http://127.0.0.1:11000;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;
    proxy_read_timeout 300s;
}

기존 설정에 location ^~ /intellidesk/가 있으면 위 정규식보다 우선하므로 해당 설정도 제거하거나 교체합니다. 배포 전 서버와 내부 에이전트의 주소를 함께 변경합니다. 앱 서버는 CODEX_INTELLIDESK_MCP_URL=http://127.0.0.1:11000/intellidesk/mcp, CODEX_SAP_MCP_URL=http://127.0.0.1:11000/sap/mcp로 지정할 수 있습니다. 미지정 시 MCP_SERVER_URL의 호스트·포트와 각 고정 경로를 사용합니다.

배포 후 인증 없이 각 endpoint를 조회하면 HTTP 401과 WWW-Authenticate가 반환되어야 합니다. 헤더의 resource_metadata URL은 HTTP 200이며, 응답의 resource는 각각의 공개 주소와 일치해야 합니다. 외부 클라이언트는 필요한 두 연결을 별도로 등록하고 각 주소로 OAuth 인증을 진행합니다.

내부 에이전트는 요청별로 사용자 인증과 MCP 연결을 분리합니다. SAP 연결 실패 시 정상적인 앱 연결은 유지하고, 앱 경로에 SAP 연결 정보를 전달하지 않습니다. 도구 승인 후에는 원래 실행의 인증 문맥으로 연결을 다시 준비합니다.

Codex의 앱 연결은 읽기 전용 조회 도구와 제품 개발 가이드를 기본 제공하며, 관리자 SAP Tool 선택과 독립적입니다. 앱 API의 사용자·테넌트 권한은 그대로 적용됩니다. 댓글 작성·이메일 발송은 Codex 기본 앱 도구에 포함하지 않습니다. 앱·SAP 서버는 같은 프로세스이므로 프로세스 자체의 중단까지 격리하는 구성은 아닙니다.

Claude에서 인증 창이 여러 개 열리는 경우

Claude Desktop이 mcp-remote로 같은 MCP 서버를 동시에 초기화할 수 있습니다. 서버는 로그인 전 확인 요청에도 OAuth 안내를 제공해 진행 중인 인증을 함께 사용하도록 지원합니다. 이전 서버에서 인증 창이 여러 개 열렸다면 MCP 서버를 갱신·재시작하고 Claude Desktop도 완전히 종료한 뒤 다시 연결합니다.

조회할 수 있는 업무

업무	요청 예시
체계도	“영업 프로세스 체계도를 보여주고 하위 프로세스를 확인해 줘.”
흐름도	“이 체계도에 연결된 프로세스 맵의 최신 버전과 활동 속성을 보여줘.”
문서	“이 프로그램의 기능 정의서와 기술 사양서를 찾아 최신 본문을 읽어줘.”
인사이트	“사양서가 없는 프로그램과 병목 액티비티를 확인해 줘.”
SAP 결과	“저장된 SAP 비교 분석을 찾아 결과와 분석 시점을 보여줘.”

문서 조회는 FUNC가 기능 정의서, TECH가 기술 사양서입니다. 버전을 지정하지 않으면 최신 버전을 선택하며 선택된 버전도 결과에 포함합니다. 목록은 페이지를 나눠 조회합니다.

SAP 저장 결과와 저장된 의존성 그래프는 SAP에 직접 연결하지 않고 조회합니다. 이번 조회 도구는 분석을 새로 실행하거나 저장 결과가 SAP의 현재 상태와 같은지 확인하지 않습니다.

MCP Apps 화면

MCP Apps를 지원하는 클라이언트에서는 체계도와 BPMN 화면이 대화 안에 표시됩니다.

1. 체계도는 하위 노드가 접힌 상태로 표시됩니다. 화살표로 필요한 하위 프로세스를 펼치고 노드를 선택합니다. 선택한 프로세스가 강조되고 오른쪽에 담당자·상태·성과 지표 등의 상세 정보가 카드로 표시됩니다.
2. 연결된 흐름도 조회를 누르고 흐름도를 선택합니다.
3. BPMN 화면에서 휠로 확대·축소하고 드래그로 이동합니다. Ctrl 키 없이도 휠을 사용할 수 있습니다. 하단의 확대, 축소, 화면 맞춤 버튼도 사용할 수 있습니다. 액티비티를 선택하면 프로그램·처리 시간·비용·추가 속성이 표시됩니다.
4. 체계도로 돌아가기로 이전 체계도를 열고 새로고침으로 현재 조회를 다시 실행합니다.
5. 오른쪽 위 최대화를 누르면 체계도나 흐름도를 전체 화면으로 크게 봅니다. 원래 크기를 누르면 대화 안 화면으로 돌아갑니다. 클라이언트가 전체 화면을 지원하지 않으면 버튼이 표시되지 않습니다.

화면에는 전체 체계도와 흐름도를 표시하고, AI에는 기본 정보와 최대 50개 항목의 요약을 전달합니다. 응답 길이에 따라 항목 수가 더 줄어들 수 있으며 전체·반환·생략 개수를 함께 안내합니다. BPMN XML과 전체 활동 속성은 화면용 데이터로 전달합니다. 특정 프로세스나 활동의 자세한 분석이 필요하면 해당 항목을 지정해 추가 조회를 요청합니다.

MCP Apps를 지원하지 않는 클라이언트에서도 같은 도구의 요약 결과를 사용할 수 있습니다. 운영자가 도구 허용 목록을 제한하면 화면의 연결 조회 버튼에 필요한 도구도 함께 허용해야 합니다.

제공 범위와 오류

새 앱 도구는 조회부터 제공합니다. 생성·수정·삭제는 후속 구현 대상입니다. 기존 SAP 개발·댓글·이메일 도구는 유지되므로 연결에 보이는 모든 도구가 조회 전용인 것은 아닙니다. 앱 조회만 필요하면 운영자에게 조회 도구만 허용하도록 요청합니다.

APP_AUTH_REQUIRED는 앱 사용자 인증을, APP_ACCESS_DENIED 또는 리소스 권한 오류는 앱에서의 접근 권한을 확인합니다. APP_API_UNAVAILABLE는 운영자에게 앱 API 연결 확인을 요청합니다. DOCUMENT_VERSION_NOT_FOUND는 저장된 문서 버전이 있는지, STANDARD_NOT_FOUND는 해당 언어의 표준 문서가 있는지 확인합니다.

도구 호출 기록은 MCP 툴 호출 기록에서 확인합니다.

오류 결과에는 code와 설명 message가 함께 포함됩니다. AUTH_EXTERNAL_TOKEN_PUBLIC_KEY_REQUIRED는 앱 서버의 공개키 설정 누락, AUTH_EXTERNAL_TOKEN_PUBLIC_KEY_UNAVAILABLE는 파일 경로·읽기 권한 문제입니다. AUTH_EXTERNAL_TOKEN_INVALID는 서명·발급자·대상 서비스 검증 실패이고 AUTH_EXTERNAL_TOKEN_VERIFICATION_CONFIG_REQUIRED는 발급자·대상 서비스 설정 누락이고 AUTH_EXTERNAL_TOKEN_EXPIRED는 재로그인이 필요한 토큰 만료입니다.