wanteddev/ennoia-plugin/ennoia-integrations

Ennoia MCP 연결 관리

외부 MCP의 서버 등록과 사용자 credential 연결을 각각 확인한다.

응답 해석과 최종 안내는 공통 응답 규칙을 적용한다.

발견

설치된 Ennoia MCP tool의 현재 schema를 사용한다. 이미 확인한 현재 선택은 재사용하고, 없을 때 get_current_ennoia_project로 확인한다. 지정한 프로젝트만 보고할 때 현재 선택을 새로 조회하지 않는다. 변경은 사용자가 지정한 단일 프로젝트에서 수행하고, 자동 선택 상태이면 먼저 명시 선택을 받는다.

1. 대상 server ID와 catalog 사실이 이미 확인됐으면 재사용한다. 없을 때 list_multi_agent_mcp_servers에 query를 넣어 서버 카탈로그를 찾는다. list_mcp_connections는 사용자 credential 연결 목록이다. 연결 목록에 없다는 이유로 서버를 새로 등록하지 않는다.
2. 대상의 상세 설정이 필요한데 아직 없을 때만 카탈로그의 server_id 또는 지원되는 exact alias로 get_ennoia_mcp_server를 조회한다. 임의의 inventory ID를 만들지 않는다.
3. 실제 사용 가능한 도구 정보가 없고 catalog discovery가 지원될 때 필요한 도구만 list_multi_agent_mcp_tools와 선택한 도구의 get_multi_agent_mcp_tool_schema로 확인한다. 도구 목록 존재와 실제 OAuth·도구 실행 성공을 구분한다.

동일 endpoint의 user 수동 서버, Plugin 서버, connector가 함께 보이면 source·scope·실제 사용 연결을 구분한다. input_schema={}는 제약이 없는 빈 schema가 반환됐다는 뜻이다. no-args 도구라고 단정하거나 정확한 인자 구조·read-only 여부·인증 완료를 추측하지 않는다. input_schema=null이나 field 누락은 schema 미확인이다. read_only=null은 자체로 인증 실패를 뜻하지 않는다. 새 availability, cause, source, next_action은 실제 응답에 있을 때만 해석한다. project catalog ready는 사용자 OAuth 도구 허가가 아니다. user_schema_discovery=unsupported에서는 사용자별 credential/schema cache나 범용 OAuth 실행 경로를 주장하지 않는다. 이 사실이 이미 확인됐으면 catalog 재조회로 사용자 권한 확인이 가능하다고 주장하지 않는다. 공식 인증 화면에서 확인하거나, 실제로 노출된 읽기 전용 실행 경로가 요청 범위에서 허용될 때만 제한적으로 확인한다. 발견된 서버와 실제 connection·실행 오류를 확인하고 기존 연결을 자동 삭제하거나 credential을 다른 source에 복사하지 않는다.

등록과 연결

새 서버가 필요한 요청이면 제공되거나 신뢰할 수 있는 설정에서 확인한 endpoint·transport·auth 방식으로 add_ennoia_mcp_server를 사용한다. endpoint를 이름에서 추측하지 않는다. 반환된 registration_id를 get_mcp_registration_status로 확인하고 next action에 따라 이어간다.

기존 서버의 개인 연결은 같은 server_id의 connect_mcp_server로 처리한다. authorization_required는 승인 대기이며 연결 완료가 아니다. 사용자가 연결 진행·링크 안내를 요청했고 응답에 authorization_url이 있으면 공통 응답 규칙에 따라 승인 링크와 실제 expires_at을 안내한다. 만료된 URL은 다시 제공하지 않고, 만료 시각이 없으면 추측하지 않는다. OAuth 승인은 사용자 본인이 진행하며 비밀번호·refresh token을 채팅으로 수집하거나 Plugin 설정·소스·로그에 저장하지 않는다. 별도 credential 입력 화면이 필요한 공급자는 host의 공식 화면을 사용하고, 화면이 없으면 Ennoia 연결 관리 화면을 안내한다.

승인 뒤 list_mcp_connections에서 같은 server_id의 connection_status=ACTIVE를 확인한다. connected=true는 연결 기록의 존재여서 EXPIRED도 포함할 수 있다. 상태가 누락·unknown이거나 결과가 서로 모순되면 미확인으로 보고한다. 완료 화면의 성공·오류 표시만으로 연결을 확정하지 않는다. ACTIVE는 개인 인증 연결 상태이며 실제 도구 실행 성공을 뜻하지 않는다. get_mcp_registration_status는 신규 등록에서 받은 registration_id에만 사용하고 개인 연결의 누락·null ID를 만들어 조회하지 않는다.

진행 중인 요청은 원래 결과를 기다리며 새 operation_id로 중복 시작하지 않는다. 유효한 동일 요청을 재전송해야 할 때는 같은 ID를 사용한다. MUTATION_RECONCILIATION_REQUIRED나 timeout처럼 결과가 불명확하면 현재 연결 상태를 확인하되, 기존 기록의 EXPIRED만으로 진행 중인 요청의 실패를 단정하지 않는다. 개인 연결의 만료·실패가 확인되고 복구가 요청됐으면 상태 확인 후 새 UUIDv4 operation_id로 같은 서버의 connect_mcp_server를 사용한다. 구 서버의 복구 문구가 새 등록을 안내하더라도 기존 개인 연결 때문에 add_ennoia_mcp_server를 호출하지 않는다. 실제 반환된 failure_stage·upstream_status만 설명하고 일반 502·UPSTREAM_UNAVAILABLE만으로 인증 만료나 공급자 장애를 추정하지 않는다.

실제 동작 확인이 요청됐다면 노출된 읽기 전용 도구를 최소 입력으로 검증한다. Ennoia가 외부 도구를 직접 호출하는 범용 도구를 제공한다고 가정하지 않는다. 필요하면 요청 범위에서 read-only graph test를 사용한다.

변경과 해제

서버 설정 변경은 update_ennoia_mcp_server, 프로젝트 사용 여부는 set_ennoia_mcp_server_enabled, 사용자 credential 해제는 disconnect_mcp_server, 서버 등록 삭제는 delete_ennoia_mcp_server다. 요청한 대상만 변경하고 등록 삭제와 개인 연결 해제를 혼동하지 않는다. 쓰기 재시도는 현재 schema의 operation_id 계약과 응답의 복구 지시를 따른다.

서버 수정은 전체 설정 교체다. 생략된 auth, static_headers, allowed_tools는 각각 none·빈 object·빈 목록으로 초기화될 수 있다. 이름만 변경해도 기존 URL·설명·인증·header·도구 허용 목록을 보존해야 한다. 상세 조회의 static_header_names는 실제 header 값이 아니며 secret도 반환하지 않는다. 기존 값을 안전하게 유지하는 공식 경로가 없다는 점이 이미 확인됐으면 같은 schema·상세 조회를 반복하지 않는다. update_ennoia_mcp_server를 호출하지 말고 Ennoia 서버 설정 화면에서 부분 변경하도록 안내한다. secret 복사 요청이나 인증을 none으로 낮추는 우회는 하지 않는다. 비밀값이 없는 서버도 현재 전체 설정을 확인하고 요청한 수정만 합쳐 전달한 뒤 결과를 재조회한다.

결과

서버 등록 상태, 사용자 연결 상태, tool discovery, 실제 실행 확인 여부를 구분해 보고한다. Auth required를 서버 부재나 장애로 단정하지 않는다.