커스텀 도구 생성

경로: 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 영역에서 문제가 생깁니다.

실패 시 점검 순서

도구 상세 Test — 에러 메시지·스택 트레이스 확인
로컬에서 동일 Command·URL 로 직접 호출해 재현 가능한지
자격 증명 유효성 — 토큰 만료·revoke, DB 계정 disable 여부
Scope/권한 부족 — 공급사 측 권한 Scope 재확인
네트워크 — 방화벽·프록시·DNS
실행 환경 — 바이너리 존재·버전·경로

두 가지 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`
Transport	`Standard I/O`	(고정)
Description	용도 메모	`사내 공유 파일시스템 MCP`
Access	`Private` / `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`
Transport	`Streamable HTTP`	(고정)
Description	용도 메모	`파트너사 벡터 검색 API`
Access	`Private` / `Public`	보통 `Private`

Connection Settings

항목	설명	예시
Endpoint URL	HTTP 스트리밍 엔드포인트	`https://example.com/api/stream`
Timeout (sec)	요청 타임아웃 (초)	`30`
Verify SSL	SSL 인증서 검증 여부	`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/O	Streamable HTTP
배포 단순성	바이너리·스크립트만 있으면 즉시 실행	서버 인프라 필요
확장성	도구 호출마다 프로세스 실행	영구 서버, 여러 호출 재사용
리소스	매 호출마다 프로세스 기동 비용	서버 상주 비용
보안 경계	Seahorse 내부 프로세스	네트워크 경계 (방화벽·SSL)
의존성 관리	실행 환경에 언어·라이브러리 필요	원격 서버가 관리
디버깅	표준 출력으로 직접 확인	HTTP 로그·원격 서버 로그

권장

간단한 사내 도구·오픈소스 MCP 서버 → Standard I/O
파트너사 API·SaaS 형태 외부 서비스 → Streamable HTTP
여러 테넌트가 공유하는 중앙 서비스 → Streamable HTTP (한 번만 배포)

등록 후 동작 검증

Save

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

Test 로 핸드셰이크 확인

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

에이전트 연결

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

대화로 검증

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 포맷·토큰 유효성 재확인

인트로

Shared (공통)

Console (콘솔)

Agent Chat (에이전트 채팅)

Billing (빌링)

Auth (인증)

Custom create

커스텀 도구 생성

두 가지 Transport

Standard I/O (stdio) 방식

Basic Information

Run Settings

Environment Variables

예시 — 사내 FileSystem MCP

Streamable HTTP 방식

Basic Information

Connection Settings

Headers

예시 — 원격 벡터 검색 MCP

stdio vs HTTP 선택 가이드

등록 후 동작 검증

운영 주의

디버깅

관련 문서

​커스텀 도구 생성

​두 가지 Transport

​Standard I/O (stdio) 방식

​Basic Information

​Run Settings

​Environment Variables

​예시 — 사내 FileSystem MCP

​Streamable HTTP 방식

​Basic Information

​Connection Settings

​Headers

​예시 — 원격 벡터 검색 MCP

​stdio vs HTTP 선택 가이드

​등록 후 동작 검증

​운영 주의

​디버깅

​관련 문서

커스텀 도구 생성

두 가지 Transport

Standard I/O (stdio) 방식

Basic Information

Run Settings

Environment Variables

예시 — 사내 FileSystem MCP

Streamable HTTP 방식

Basic Information

Connection Settings

Headers

예시 — 원격 벡터 검색 MCP

stdio vs HTTP 선택 가이드

등록 후 동작 검증

운영 주의

디버깅

관련 문서