Skip to main content

​
커스텀 도구 생성

경로: Console → Agent Ops → Tool Management → + 도구 생성 → Quick Setup 아래의 Custom 선택 서비스 템플릿(GitHub·Atlassian·PostgreSQL·Slack) 이 제공하지 않는 MCP 서버를 직접 등록합니다. Standard I/O (로컬 프로세스) 와 Streamable HTTP (원격 서버) 두 가지 Transport 를 지원합니다.
커스텀 도구 등록 실패의 대부분은 사전 확인 누락에서 생깁니다. 아래 5 가지를 먼저 점검하세요. 공식 지원 범위를 벗어난 MCP 서버는 Seahorse 에서 동작·호환성을 보장하지 않습니다.
1. MCP 서버 자체가 동작하는지 먼저 로컬 검증
  • stdio 방식이면 Command + Args 를 로컬 터미널에서 직접 실행 해 MCP 서버 프로세스가 정상 기동되는지 확인
  • HTTP 방식이면 Endpoint URL 에 curl 로 요청 해 응답이 돌아오는지 확인
  • list_tools 같은 MCP 기본 호출이 정상 응답해야 Seahorse 에서도 성공합니다
2. 인증·권한 사전 준비
  • MCP 서버가 요구하는 자격 증명(API 토큰·DB 계정·SSL 인증서) 이 발급되었는지
  • 외부 서비스 측에서 필요한 권한(Scope / Role) 이 승인 되었는지
  • 만료일·Rotation 정책 확인 — 만료된 토큰은 조용히 실패합니다
3. 네트워크 도달 가능성
  • Seahorse 에이전트 서버가 MCP 서버(또는 대상 API) 에 네트워크로 접근 가능한지
  • 사내 프록시·방화벽·VPC·보안 그룹에서 포트·도메인 허용
  • HTTP 방식은 TLS 인증서 유효성 확인 (Verify SSL: true 기준)
4. 의존성·실행 환경
  • stdio: npx / python / uvx 같은 실행 바이너리가 Seahorse 에이전트 서버에 설치·접근 가능한지
  • 패키지 버전 고정 (@pkg@1.2.3) — @latest 는 업스트림 변경으로 갑자기 깨질 수 있음
5. 공식 지원 범위 확인
  • 업스트림(MCP 서버 저장소) 변경, 드라이버 버전, 네트워크·인증 구성에 따라 연결 실패·타임아웃·도구 스펙 불일치 가 발생할 수 있습니다
  • 등록 후 반드시 도구 상세 의 Test 로 핸드셰이크·list_tools 응답을 사전 검증
  • 운영 환경 배포 전 개발/스테이징 테넌트에서 먼저 검증 하고, 실패 패턴(인증·타임아웃·Rate Limit) 파악
  • 공식 지원이 필요한 도구는 고객지원 창구 로 요청 — 수요에 따라 향후 템플릿으로 추가될 수 있음
등록 후 실패 시에는 아래 순서로 점검 하세요. 대부분 자격 증명·네트워크·실행 환경 3 영역에서 문제가 생깁니다.
실패 시 점검 순서
  1. 도구 상세 Test — 에러 메시지·스택 트레이스 확인
  2. 로컬에서 동일 Command·URL 로 직접 호출해 재현 가능한지
  3. 자격 증명 유효성 — 토큰 만료·revoke, DB 계정 disable 여부
  4. Scope/권한 부족 — 공급사 측 권한 Scope 재확인
  5. 네트워크 — 방화벽·프록시·DNS
  6. 실행 환경 — 바이너리 존재·버전·경로

​
두 가지 Transport

Transport설명언제 쓰나
Standard I/O (stdio)로컬 프로세스를 실행하고 stdin/stdout 으로 통신자체 개발 MCP, 사내 전용 도구, npm/pip 로 배포되는 MCP 서버
Streamable HTTP원격 HTTP 엔드포인트로 스트리밍 통신이미 서버 인프라가 있는 외부 MCP, SaaS 형태로 제공되는 MCP
템플릿 4 종(GitHub·Atlassian·PostgreSQL·Slack) 은 모두 Standard I/O 방식입니다. HTTP 방식은 확장성·중앙 관리가 필요할 때 선택하세요.

​
Standard I/O (stdio) 방식

로컬에서 프로세스를 실행해 MCP 서버로 동작시킵니다.

​
Basic Information

필드설명예시
Name도구 이름internal-fs-mcp
TransportStandard I/O(고정)
Description용도 메모사내 공유 파일시스템 MCP
AccessPrivate / Public보통 Private

​
Run Settings

항목설명예시
Command실행 바이너리·명령python, node, npx, /usr/bin/python3, uvx
Args명령 인자 (여러 개 가능, Add Argument)-u, /app/internal-fs-mcp/server.py

​
Environment Variables

Add Environment Variable 로 필요한 키-값 추가. 각 변수마다 다음 3 가지 타입 중 선택:
타입의미입력 필드
User Input사용자가 도구 생성/편집 화면에서 직접 입력값 입력 필드 활성
System Default운영자가 Environment 에 세팅한 값을 런타임에 자동 주입This value is fixed and automatically used at runtime 표시
고정값템플릿에 박힌 상수 (포트·경로 등)값이 미리 채워짐

​
예시 — 사내 FileSystem MCP

name: internal-fs-mcp
transport: Standard I/O
command: node
args:
  - /app/internal-fs-mcp/dist/index.js
env:
  - key: FS_ROOT
    value: /data/tenant-shared
    type: System Default
  - key: MAX_FILE_SIZE
    value: "100MB"
    type: User Input

​
Streamable HTTP 방식

원격 MCP 서버에 HTTP 스트리밍으로 접속합니다.

​
Basic Information

필드설명예시
Name도구 이름external-vector-search
TransportStreamable HTTP(고정)
Description용도 메모파트너사 벡터 검색 API
AccessPrivate / Public보통 Private

​
Connection Settings

항목설명예시
Endpoint URLHTTP 스트리밍 엔드포인트https://example.com/api/stream
Timeout (sec)요청 타임아웃 (초)30
Verify SSLSSL 인증서 검증 여부True (운영 권장) / False (개발 환경만)

​
Headers

Add Header 로 요청 헤더 추가. 일반적으로:
헤더용도
Authorization: Bearer {token}인증
X-API-Key: {key}API 키 인증
Content-Type: application/json통신 포맷 지정

​
예시 — 원격 벡터 검색 MCP

name: external-vector-search
transport: Streamable HTTP
endpoint: https://api.partner.com/mcp/stream
timeout: 30
verify_ssl: true
headers:
  - key: Authorization
    value: "Bearer xyz..."
  - key: X-Tenant-Id
    value: "seahorse-prod"

​
stdio vs HTTP 선택 가이드

기준Standard I/OStreamable HTTP
배포 단순성바이너리·스크립트만 있으면 즉시 실행서버 인프라 필요
확장성도구 호출마다 프로세스 실행영구 서버, 여러 호출 재사용
리소스매 호출마다 프로세스 기동 비용서버 상주 비용
보안 경계Seahorse 내부 프로세스네트워크 경계 (방화벽·SSL)
의존성 관리실행 환경에 언어·라이브러리 필요원격 서버가 관리
디버깅표준 출력으로 직접 확인HTTP 로그·원격 서버 로그
권장
  • 간단한 사내 도구·오픈소스 MCP 서버 → Standard I/O
  • 파트너사 API·SaaS 형태 외부 서비스 → Streamable HTTP
  • 여러 테넌트가 공유하는 중앙 서비스 → Streamable HTTP (한 번만 배포)

​
등록 후 동작 검증

1

Save

Save 클릭 → 도구 목록에 등록.
2

Test 로 핸드셰이크 확인

도구 상세 의 Test 버튼 → MCP 핸드셰이크 + list_tools 호출 → 지원 메서드가 채워짐.
3

에이전트 연결

Agent 수정 → Tools 탭 에서 새 도구 체크 → Save.
4

대화로 검증

Agent Chat 에서 해당 도구가 쓰일 법한 질의를 보내 실제 호출 확인.

​
운영 주의

  • Command 에 파괴적 명령 금지 — rm -rf · dd 같은 시스템 레벨 명령을 Args 에 넣지 말 것.
  • 절대경로 사용 — command: python 보다는 /usr/bin/python3 이 환경 변동에 강함.
  • 비밀값은 환경변수 — 토큰·비밀번호를 Args 에 넣지 말고 System Default 환경변수 로 전달 (감사 로그에 인자가 남습니다).
  • Streamable HTTP 의 Verify SSL: False 는 개발용만 — 운영 환경은 반드시 True.
  • Timeout 설정 — 너무 짧으면 정상 호출도 실패, 너무 길면 에이전트 응답 지연. 도구 특성에 맞춰 10–60 초가 일반적.
  • 의존성 버전 고정 — npx @pkg@latest 보다 npx @pkg@1.2.3 로 버전 고정. 업스트림 변경으로 도구가 갑자기 실패하는 상황 방지.

​
디버깅

  • Test 에서 실패 → 로컬에서 직접 Command + Args 실행해 MCP 서버 기동 여부·포트 응답 확인
  • 도구 호출 후 에러 → 도구 상세 의 호출 로그에서 stderr / HTTP 응답 확인
  • 환경변수 미주입 → System Default 타입인지, Environment 에 값이 있는지 확인
  • HTTP 403/401 → 헤더 Authorization 포맷·토큰 유효성 재확인

​
관련 문서