Didit MCP 서버 자체 호스팅 가이드
Docker 또는 Node를 사용하여 오픈 소스 Didit MCP 서버를 배포하고, OAuth 또는 헤드리스 stdio를 구성한 다음, 자체 로드 밸런서 뒤에서 스테이트리스 서비스를 실행하는 방법을 알아보세요.
주요 내용
- Didit Model Context Protocol(MCP) 서버는 MIT 라이선스에 따라 오픈 소스입니다. 공개 GitHub 저장소에서 빌드하여 Docker, Node.js 또는 헤드리스 stdio 전송으로 실행할 수 있습니다.
- 자체 호스팅은 MCP 프로세스가 Didit에 도달하는 방식이 아니라 실행되는 위치를 변경합니다. 모든 모드는 Bearer 액세스 토큰을 사용하여 Didit 사용자로서 인증합니다. MCP 도구에는 애플리케이션 API 키 모드가 없습니다.
- 전체 자체 호스팅 카탈로그에는 121개의 도구가 포함되어 있습니다. 호스팅된 Open Authorization(OAuth) 엔드포인트는 의도적으로 115개를 노출합니다. 현재 소스의 예시에는
didit_context_get,didit_session_create및didit_transaction_screen_wallet이 포함됩니다. - HTTP 진입점은 스테이트리스이며 POST 요청을 통해 MCP 트래픽을 수락합니다. 요청당 새로운 서버와 전송이 생성되므로 로드 밸런서에 세션 선호도가 필요하지 않습니다.
- 컨테이너 및 로드 밸런서 검사에는
/healthz를 사용합니다. 서비스를 노출하기 전에 공개 리소스 URI, 권한 부여 원본, 토큰 확인 모드 및 비밀을 명시적으로 구성하십시오.
호스팅된 엔드포인트는 편리하지만 모든 팀에 적합한 운영 선택은 아닙니다. 기업은 통합을 자체 네트워크 경계 내에 유지하거나, 런타임 이미지를 제어하거나, 개인 이그레스 계층을 통해 트래픽을 라우팅하거나, 자체 관찰 가능성 및 변경 관리 정책을 적용해야 할 수 있습니다. Didit MCP 저장소는 별도의 제품 표면을 만들지 않고도 해당 배포 모델을 지원합니다.
이 가이드는 서버 운영에만 중점을 둡니다. 카탈로그 및 도구 동작에 대해서는 Didit MCP 도구 참조를 사용하십시오. 관리형 엔드포인트에 대한 클라이언트 설정에 대해서는 Claude 설치 가이드를 사용하십시오. 전체 기술 참조는 MCP 개요 및 인증 문서에 있습니다.
HTTP 또는 stdio 진입점 선택
저장소는 두 개의 진입점을 가진 하나의 공유 도구 카탈로그를 빌드합니다. dist/http.js는 스테이트리스 Streamable HTTP를 통해 Express 리소스 서버를 실행합니다. 여러 MCP 클라이언트, 컨테이너 또는 사용자가 도달하는 공유 서비스에 적합한 선택입니다. dist/index.js는 stdio를 통해 실행되며 하나의 클라이언트에서 시작하는 헤드리스 로컬 프로세스용으로 설계되었습니다.
두 진입점 모두 동일한 디스패치 로직을 호출하며, 버전 5는 MCP 리소스나 프롬프트가 아닌 MCP 도구만 노출합니다. 둘 다 다운스트림 요청을 Didit 사용자로 인증합니다. 차이점은 해당 사용자 자격 증명이 프로세스에 도달하는 방식입니다. HTTP 진입점은 호출자의 OAuth Bearer 토큰을 수신하고 유효성을 검사합니다. stdio 진입점은 DIDIT_ACCESS_TOKEN에서 사용자 Bearer 토큰을 읽습니다.
자체 호스팅이 자격 증명 없이 작동한다는 의미는 아닙니다. MCP는 여전히 Didit 사용자 역할을 하며, Didit은 해당 사용자의 조직 역할 및 권한을 모든 도구 호출에 적용합니다.
Docker로 빌드 및 실행
저장소에는 Node 20을 기반으로 하는 다단계 Dockerfile이 포함되어 있습니다. 빌드 단계는 개발 종속성을 설치하고, TypeScript를 컴파일하고, 개발 패키지를 정리합니다. 프로덕션 단계는 비루트 node 사용자로 실행되며 컨테이너 상태 검사를 포함합니다.
git clone https://github.com/didit-protocol/mcp.git
cd mcp
cp .env.example .env
docker build -t didit-mcp .
docker run -p 3000:3000 --env-file .env didit-mcp컨테이너를 시작하기 전에 배포를 식별하는 호스팅된 기본값을 교체하십시오. 최소한 MCP_RESOURCE_URI를 클라이언트가 이 리소스 서버에 도달하는 공개 원본으로 설정한 다음, 토큰 인트로스펙션에 필요한 OAuth 클라이언트 자격 증명을 제공하십시오. 채워진 .env 파일을 커밋하는 대신 컨테이너 플랫폼의 비밀 관리자에 비밀을 보관하십시오.
MCP_PORT=3000
MCP_RESOURCE_URI=https://mcp.example.com
MCP_AUTHORIZATION_SERVER_ORIGIN=https://business.didit.me
MCP_TOKEN_VERIFY_MODE=introspection
MCP_OAUTH_CLIENT_ID=replace-with-client-id
MCP_OAUTH_CLIENT_SECRET=replace-with-client-secret
MCP_SCOPES_SUPPORTED="didit:management didit:verification"인그레스 또는 로드 밸런서에서 TLS(Transport Layer Security)를 종료하고, MCP POST 요청을 포트 3000으로 전달하고, Authorization 헤더를 유지하십시오. 외부적으로 보이는 MCP_RESOURCE_URI는 클라이언트에 광고되는 리소스 ID와 일치해야 합니다. 다른 공개 원본에 대해 관리되는 Didit URI를 그대로 두지 마십시오.
Node.js로 직접 빌드 및 실행
플랫폼이 이미 Node 런타임을 관리하는 경우 컨테이너 없이 동일한 HTTP 진입점을 사용하십시오. 패키지는 비공개이며 npm을 통해 배포되지 않으므로 게시된 패키지를 실행하려고 시도하는 대신 저장소를 복제하십시오.
git clone https://github.com/didit-protocol/mcp.git
cd mcp
npm install
npm run build
node dist/http.js프로세스는 컨테이너와 동일한 환경 변수를 읽습니다. 프로세스 관리자 아래에서 실행하고, 배포 환경을 통해 비밀을 주입하고, 필요한 엔드포인트만 라우팅하십시오. MCP 요청은 POST /mcp로 이동합니다. 서비스는 MCP 세션이나 서버 시작 스트림을 유지하지 않으므로 해당 경로에서 GET 및 DELETE를 의도적으로 거부합니다.
Node.js는 저장소의 .env 파일을 자동으로 로드하지 않습니다. dist/http.js를 시작하기 전에 쉘에서 값을 내보내거나 서비스 관리자를 통해 주입하거나 플랫폼의 환경 파일 지원을 사용하십시오. 또한 npm start는 stdio 진입점을 시작합니다. HTTP의 경우 node dist/http.js 또는 npm run start:http를 사용하십시오.
stdio를 통해 헤드리스 실행
로컬 에이전트, 빌드 러너 또는 격리된 단일 클라이언트 프로세스의 경우 stdio 진입점을 사용하십시오. 환경을 통해 사용자 액세스 토큰을 제공하고 MCP 클라이언트가 프로세스 수명 주기를 소유하도록 하십시오.
DIDIT_ACCESS_TOKEN=<user-access-token> node dist/index.js이 토큰은 애플리케이션 자격 증명이 아니라 사용자 Bearer 자격 증명입니다. 비밀로 저장하고, 쉘 기록 및 로그에 기록되지 않도록 하며, 액세스 정책에 따라 순환하십시오. 하나의 배포가 항상 하나의 조직 또는 애플리케이션에서 작동하는 경우 MCP_DEFAULT_ORG 및 MCP_DEFAULT_APP이 해당 기본 범위를 제공할 수 있습니다. 그렇지 않으면 도구는 명시적 인수 또는 인증된 요청 컨텍스트에서 범위를 확인할 수 있습니다.
stdio에는 여전히 애플리케이션 API 키 모드가 없습니다. 자체 호스팅 HTTP와 자체 호스팅 stdio는 모두 사용자 범위의 Didit 콘솔 엔드포인트를 호출하므로 애플리케이션 키는 사용자 Bearer 토큰을 대체할 수 없습니다.
전체 환경 표면 구성
현재 src/config.ts는 다음 변수를 지원합니다. 대부분의 배포는 프로덕션 Didit API 및 인증 기본값을 유지하고 토폴로지에 필요한 리소스 ID, 확인 구성 및 비밀만 재정의해야 합니다.
공유 및 stdio 변수
DIDIT_ACCESS_TOKEN: 헤드리스 stdio 모드용 사용자 Bearer 토큰; 기본값 없음.DIDIT_API_BASE_URL: 확인 API 기본값; 기본값은https://verification.didit.me/v3입니다.DIDIT_AUTH_BASE_URL: 인증 API 기본값; 기본값은https://apx.didit.me/auth/v2입니다.MCP_DEFAULT_ORG및MCP_DEFAULT_APP: 단일 테넌트 배포를 위한 선택적 조직 및 애플리케이션 기본값.
HTTP 리소스 서버 변수
MCP_PORT: 수신 포트; 기본값은3000입니다.MCP_RESOURCE_URI: 공개 리소스 서버 URI; 기본값은https://mcp.didit.me입니다.MCP_AUTHORIZATION_SERVER_ORIGIN: 권한 부여 서버 원본; 기본값은https://business.didit.me입니다.MCP_TOKEN_VERIFY_MODE: 기본값은introspection이며, 권한 부여 서비스가 로컬 서명 확인에 적합한 JSON 웹 토큰(JWT)을 발행할 때는jwks입니다.MCP_OAUTH_CLIENT_ID및MCP_OAUTH_CLIENT_SECRET: 기본값 없음; RFC(Request for Comments) 7662 인트로스펙션용 HTTP 기본 자격 증명으로 사용됩니다.MCP_OAUTH_INTROSPECT_URL: 기본값은https://apx.didit.me/auth/v2/introspect/입니다.MCP_SCOPES_SUPPORTED: 공백으로 구분된 검색 범위; 기본값은didit:management didit:verification입니다.
권한 부여 메타데이터 재정의
DIDIT_AUTH_ISSUER: 기본값은MCP_AUTHORIZATION_SERVER_ORIGIN입니다.DIDIT_OIDC_DISCOVERY_URL: OpenID Connect(OIDC) 검색 문서; 기본값은 권한 부여 원본에/.well-known/oauth-authorization-server를 더한 값입니다.DIDIT_JWKS_URL: JSON 웹 키 세트(JWKS) 엔드포인트; 기본값은https://apx.didit.me/auth/config/jwks/입니다.DIDIT_OIDC_AUTHORIZE_URL: 기본값은 권한 부여 원본에/authorize를 더한 값입니다.DIDIT_OIDC_TOKEN_URL: 기본값은 권한 부여 원본에/api/auth/oauth-token을 더한 값입니다.DIDIT_OIDC_REGISTRATION_URL: 기본값은 권한 부여 원본에/api/auth/oauth-register를 더한 값입니다.
불투명 액세스 토큰에는 introspection을 사용하십시오. 서버는 MCP_OAUTH_CLIENT_ID 및 MCP_OAUTH_CLIENT_SECRET을 사용하여 구성된 인트로스펙션 엔드포인트로 전송합니다. 권한 부여 서비스가 이 클라이언트에 대해 서명된 JWT 액세스 토큰을 발행하도록 구성된 경우에만 jwks를 사용하십시오. 그러면 서버는 DIDIT_JWKS_URL에 대해 서명을 검증합니다. 확인 모드를 변경해도 다른 ID 모델이 생성되지는 않습니다. 검증된 주체는 여전히 Didit 사용자입니다.
MCP 클라이언트는 권한 부여 흐름 중에 Didit Business Console과 함께 DCR(Dynamic Client Registration)을 사용할 수 있습니다. 해당 클라이언트 등록은 인트로스펙션 요청을 인증하는 리소스 서버의 MCP_OAUTH_CLIENT_ID 및 MCP_OAUTH_CLIENT_SECRET과는 별개입니다. 클라이언트 등록이 이를 대체할 수 있다고 가정하지 말고 적절한 Didit 배포 채널을 통해 서버 측 자격 증명을 프로비저닝하십시오.
상태 확인 및 스테이트리스 스케일링
HTTP 프로세스는 GET /healthz를 노출하고 status, service 및 version을 포함하는 JSON을 반환합니다. Docker 이미지는 15초 시작 기간 후 30초마다 이를 이미 확인합니다. Kubernetes 준비 상태, Application Load Balancer 대상 그룹 또는 외부 업타임 프로브에 동일한 엔드포인트를 사용할 수 있습니다.
curl -fsS http://localhost:3000/healthzMCP 경로는 설계상 스테이트리스입니다. 인증된 모든 POST에 대해 프로세스는 세션 생성이 비활성화된 새로운 서버와 Streamable HTTP 전송을 생성하고, 호출자의 유효성 검사된 자격 증명을 요청별 컨텍스트를 통해 전달하고, 디스패치를 완료하고, 전송을 닫습니다. 나중에 요청이 동일한 복제본에서 찾아야 하는 인메모리 세션은 없습니다.
여기서 스테이트리스는 MCP 전송 및 요청 수명 주기를 설명합니다. 확인 세션, 워크플로, 사례 및 기타 비즈니스 기록은 여전히 Didit의 업스트림 서비스에 유지됩니다.
결과적으로 수평 복제본은 고정 세션이 필요하지 않습니다. 모든 정상 인스턴스는 다음 POST를 처리할 수 있으며, 롤링 배포는 일반적인 진행 중인 요청 처리 외에 세션 드레이닝을 요구하지 않습니다. 용량 계획은 요청 동시성, 다운스트림 Didit API 대기 시간, 일반적인 시간 초과 및 재시도 정책에 중점을 두어야 합니다.
서비스 노출 전 유효성 검사
- 로드 밸런서와 동일한 네트워크 경로에서
/healthz가 성공하는지 확인하십시오. - 인증되지 않은 MCP 요청이 도구 출력이 아닌 권한 부여 챌린지를 수신하는지 확인하십시오.
- PKCE(Proof Key for Code Exchange)를 사용하여 OAuth 2.1 흐름을 완료한 다음,
didit_context_get을 호출하여 예상되는 조직 및 애플리케이션이 보이는지 확인하십시오. - 검색 엔드포인트 또는 토큰 확인을 변경하기 전에 고급 MCP 문서를 검토하십시오.
- 지원되는 관리형 표면 및 현재 링크는 Didit MCP 개발자 페이지를 참조하십시오.
자체 호스팅이 더 이상 요구 사항이 아닌 경우, 관리형 엔드포인트는 위에서 설명한 런타임 및 OAuth 리소스 서버 작업을 제거합니다. Claude 사용자는 Didit 커넥터 딥 링크를 통해 이를 추가할 수 있습니다. 프로세스를 실행하는 것이 Didit이든 아니든 핵심 규칙은 동일합니다. MCP 작업은 애플리케이션 API 키가 아닌 Didit 사용자로서 인증합니다.