Deep Agent Builder MCP와 에이전트의 MCP화
이 페이지는 에이전트에 MCP를 연결할 때 확인할 설정 경계와 실행 결과를 설명합니다. MCP를 켜는 것과 에이전트가 MCP 도구를 실제로 실행하는 것은 같은 작업이 아닙니다. 연결 설정, 권한, 실행 문맥과 외부 서버 상태를 순서대로 확인해야 합니다.
MCP를 에이전트에 연결하면 무엇이 달라지는가
에이전트 설정에는 MCP 활성화 여부가 포함됩니다. MCP 설정은 에이전트의 일반 이름이나 지침과 별도 자원으로 관리되며, 설정 조회와 변경도 별도 경로를 사용합니다. 따라서 에이전트가 존재하고 실행 가능한 상태여도 MCP 설정이 비어 있거나 비활성화돼 있으면 MCP 도구를 사용할 수 없습니다.
MCP 연결 정보에는 이름과 설명, 연결 식별 정보가 포함될 수 있습니다. 연결 설정에 시크릿이 필요한 경우에는 실제 값을 일반 설정이나 문서에 복사하지 말고 제품이 요구하는 시크릿 참조와 실행 환경을 따로 확인합니다. 저장된 설정과 이번 discovery 또는 실행에 필요한 자격 증명은 같은 것으로 취급하지 않습니다.
MCP를 연결한 뒤에는 다음 세 가지를 따로 판단해야 합니다.
| 확인 대상 | 확인할 내용 | 성공으로 볼 수 있는 범위 |
|---|---|---|
| 설정 | MCP가 활성화됐고 연결 정보가 저장됐는가 | 에이전트 설정이 저장된 상태 |
| discovery | 외부 MCP 서버에서 사용할 도구와 하위 도구를 찾았는가 | 연결된 도구 목록을 확인할 수 있는 상태 |
| 실행 | 현재 에이전트와 실행 문맥으로 도구를 호출했는가 | 실제 입력에 대한 호출 결과를 받은 상태 |
설정 저장이나 도구 목록 확인만으로 업무 실행이 성공했다고 결론 내리면 안 됩니다.
연결 전에 확인할 것
먼저 에이전트의 사용 권한과 MCP 설정을 변경할 권한을 구분합니다. 에이전트와 MCP 설정을 조회하려면 조회 권한이 필요하고, MCP 설정을 바꾸려면 편집 권한이 추가로 필요합니다. 도구를 읽거나 실행하는 권한은 에이전트 설정 권한과 별도로 확인해야 합니다.
다음으로 연결 유형과 외부 서버의 준비 상태를 확인합니다.
- 사용할 MCP 서버의 연결 방식과 endpoint를 확인합니다.
- 필요한 headers, 환경 변수, 인증 참조를 준비합니다.
- 저장할 설정에 실제 시크릿 값이 남지 않는지 확인합니다.
- MCP 서버가 제공하는 도구와 하위 도구의 이름, 입력 형식을 확인합니다.
- 비식별 테스트 입력으로 discovery와 실행을 각각 시험합니다.
MCP-over-HTTP 개인 도구를 새로 등록하는 경우에는 도구 유형을 MCP HTTP로 지정하고 variant도 함께 확인해야 합니다. MCP HTTP에서 variant를 생략하면 등록 검증이 실패할 수 있습니다. 일반 HTTP 도구의 설정 규칙을 MCP 설정에 그대로 적용하지 마세요.
MCP 설정과 도구 목록을 확인하는 순서
에이전트 설정 화면이나 승인된 API 경로에서 MCP 활성화 상태와 연결 정보를 확인합니다. 제품 화면에서 실제 메뉴와 버튼을 확인하기 전에는 화면 라벨이나 성공 메시지를 기준으로 판단하지 않습니다.
설정을 저장한 뒤에는 에이전트에 표시되는 도구 목록을 다시 조회합니다. 목록에 도구가 보이지 않으면 다음 순서로 원인을 좁힙니다.
- MCP 설정이 활성화돼 있는지 확인합니다.
- 연결 endpoint와 인증 참조가 현재 환경에서 유효한지 확인합니다.
- discovery에 필요한 시크릿이 준비됐는지 확인합니다.
- 외부 서버가 도구 목록을 반환하는지 확인합니다.
- 하위 도구 이름과 입력 스키마가 에이전트에 전달됐는지 확인합니다.
- 에이전트가 해당 도구를 사용할 권한을 갖는지 확인합니다.
Discovery가 실패하면 저장된 연결 정보와 일회성 discovery 입력을 혼동하지 마세요. 필요한 자격 증명이 없을 때는 외부 호출 전에 갱신이 중단될 수 있습니다.
MCP 도구를 실행할 때의 경계
실행 요청에는 도구 입력뿐 아니라 현재 사용자, 실행, 에이전트, 대화와 같은 실행 문맥이 함께 필요합니다. 문맥이 불완전하거나 현재 실행과 일치하지 않으면 호출은 실행되지 않습니다. 서버는 권한과 소유자, 실행 상태와 문맥의 일치를 확인한 뒤 MCP 도구를 호출합니다.
MCP 도구가 오래 걸리면 실행은 정해진 시간까지 대기하거나 timeout으로 끝날 수 있습니다. 연결 단계에서 일시적인 연결 오류를 다시 시도할 수 있지만, 이미 외부 서버에 도달했을 수 있는 요청이나 HTTP 오류를 무조건 다시 보내지는 않습니다. 같은 작업이 중복 실행될 수 있는지 먼저 확인해야 합니다.
성공한 결과는 에이전트가 읽을 수 있는 도구 결과로 전달되고, 원본 실행 봉투는 별도 artifact로 보존될 수 있습니다. 외부 MCP 서버가 오류를 반환하거나 하위 도구를 찾지 못하거나 세션이 끊기면 실행 결과는 도구 오류로 수렴합니다. 도구 오류 하나만으로 전체 실행이 항상 즉시 종료된다고 가정하지 마세요. 실제 화면과 실행 상태에서 오류 범위를 확인해야 합니다.
실패 원인별 다음 판단
| 관찰한 상태 | 먼저 확인할 것 | 다음 판단 |
|---|---|---|
| MCP 설정을 저장할 수 없음 | 편집 권한, endpoint 형식, variant, 필수 인증 참조 | 설정 검증을 먼저 통과시킨 뒤 discovery를 다시 시도 |
| 설정은 저장됐지만 도구가 보이지 않음 | discovery 시크릿, 외부 서버의 도구 목록, 도구 유형 | 저장 성공과 discovery 성공을 분리해 기록 |
| 도구는 보이지만 호출이 실패함 | 도구 사용 권한, 하위 도구 이름, 입력 스키마 | 연결이 아니라 실행 입력과 권한을 점검 |
| 실행이 오래 걸리거나 timeout | 외부 서버 응답 시간, 입력 범위, 현재 실행의 deadline | 같은 요청을 반복하기 전에 외부 작업의 중복 여부 확인 |
| MCP 세션 또는 서비스 오류 | 외부 서버 상태, endpoint 접근 정책, trace와 실행 상태 | 새 요청 전 실패 범위와 재시도 가능성을 확인 |
오류 메시지에 endpoint, 인증값, 고객 데이터가 포함돼 있다면 공개 문서나 캡처에 복사하지 않습니다. 로그와 화면을 공유할 때도 실제 값 대신 승인된 비식별 자료를 사용합니다.
완료 확인
MCP 연결 작업은 다음 네 가지가 모두 확인돼야 완료로 봅니다.
- MCP 설정이 의도한 에이전트에 저장돼 있습니다.
- 에이전트에 필요한 도구와 하위 도구가 표시됩니다.
- 테스트 입력으로 실제 호출 결과 또는 재현 가능한 오류가 확인됩니다.
- 설정 권한, 도구 사용 권한, 외부 서버 상태를 구분해 기록했습니다.
도구 목록이 보인다는 사실만으로 실제 업무 입력이 처리된 것은 아닙니다. 반대로 테스트 실행이 실패했다고 해서 설정 저장까지 실패했다고 단정하지 말고, 어느 단계에서 멈췄는지 분리해 확인하세요.