본문으로 건너뛰기

MCP 서버

외부 MCP 서버를 연결하고 확인합니다.

이 페이지

외부 MCP 서버를 등록하면 Butler가 대화 중 그 서버의 도구를 호출하고 리소스를 읽을 수 있습니다. 이 문서는 Butler가 다른 서버에 접속하는 경우를 다룹니다. Butler를 다른 MCP 클라이언트에 연결하는 방법은 MCP 서버로 쓰기를 참고합니다.

MCP 서버 추가하기

  1. 사이드바에서 설정을 열고 MCP를 선택합니다.
  2. MCP 서버 추가를 누릅니다.
  3. 서버 ID와 표시 이름을 입력합니다.
  4. 연결 방식에서 stdio, Streamable HTTP, SSE 중 하나를 고릅니다.
  5. 연결 방식에 맞는 항목을 채웁니다.
  6. 저장을 누릅니다.
  7. 목록에서 추가한 서버의 연결 확인(새로고침 아이콘)을 눌러 연결되는지 확인합니다.

새 서버는 사용이 켜진 상태로 폼이 열립니다. 끈 채로 저장하면 비활성 상태로 추가됩니다.

공통 항목

  • 서버 ID — Butler가 서버를 구분하는 ID입니다. 반드시 입력합니다. 소문자로 바뀌고, 영문자·숫자·.·_·- 외의 문자는 -로 바뀝니다. 최대 80자입니다.
  • 표시 이름 — 목록에 보이는 이름입니다. 비워 두면 서버 ID를 씁니다.
  • 연결 방식 — stdio, Streamable HTTP, SSE 중 하나입니다.
  • 사용 — 끄면 Butler가 대화 중 이 서버를 쓰지 않습니다.

연결 방식별 항목

stdio

Butler가 로컬에서 명령을 실행하고 표준 입출력으로 통신합니다.

  • 명령 — 실행할 프로그램입니다. 반드시 입력합니다.
  • 인자 — 명령에 넘길 인자를 한 줄에 하나씩 입력합니다. 빈 줄은 무시합니다.
  • 작업 폴더 — 명령을 실행할 폴더입니다.
  • 환경 변수 — 서버 프로세스에 넘길 환경 변수입니다.

Streamable HTTP와 SSE

Butler가 HTTP로 이미 실행 중인 서버에 접속합니다. 서버가 지원하는 방식을 고릅니다. SSE는 이전 HTTP+SSE 방식만 지원하는 서버에 씁니다.

  • URL — 서버 주소입니다. 반드시 입력하며 http:// 또는 https://로 시작해야 합니다.
  • 헤더 — 요청마다 보낼 HTTP 헤더입니다. 인증 토큰은 Authorization 같은 헤더로 넘깁니다.

환경 변수와 헤더 입력하기

환경 변수와 헤더는 행 단위로 입력합니다. 각 행은 출처, 키, 값으로 구성됩니다.

  1. 환경 변수 추가 또는 헤더 추가를 누릅니다.
  2. 행의 출처를 고르고 키와 값을 입력합니다.
  3. 여러 행의 출처를 한 번에 바꾸려면 위쪽 출처 선택에서 출처를 고르고 전체 출처 적용을 누릅니다.

출처는 세 가지입니다.

  • 직접값 — 입력한 값을 그대로 저장합니다. 저장한 뒤에는 화면과 API 응답에 값을 다시 표시하지 않습니다.
  • ENV 참조 — 값 칸에 환경 변수 이름을 적습니다. 연결할 때 Butler Agent의 환경 변수에서 값을 읽습니다.
  • 파일 — 값 칸에 파일 경로를 적습니다. 연결할 때 파일 내용을 읽고 끝의 공백과 줄바꿈을 지웁니다.

위쪽 출처 선택은 새로 추가하는 행의 기본 출처로도 쓰입니다. 키에는 영문자, 숫자, _, ., -만 남고 나머지 문자는 _로 바뀝니다. 키나 값이 비어 있는 행은 저장하지 않습니다.

수정할 때 직접값 행의 값 칸은 비어 있습니다. 비워 두면 저장된 값을 유지하고, 새 값을 입력하면 교체합니다. 행을 지우고 저장하면 그 값도 삭제됩니다.

서버 관리하기

목록의 각 서버에는 표시 이름과 함께 연결 방식, 명령 또는 URL, 등록한 환경 변수·헤더 수가 표시됩니다.

  • 연결 확인(새로고침 아이콘) — 서버에 접속해 도구와 리소스 목록을 가져옵니다. 비활성 서버도 확인할 수 있습니다.
  • 활성화 / 비활성화 — 서버 사용 여부를 바꿉니다. 켜진 서버에는 비활성화가, 꺼진 서버에는 활성화가 보입니다.
  • 수정(연필 아이콘) — 아래에 편집 폼을 엽니다.
  • 삭제(휴지통 아이콘) — 서버를 목록에서 지웁니다.

등록한 서버 설정은 ~/.butler/config/mcp-servers.json에 저장됩니다.

Butler가 MCP 서버를 쓰는 방식

  • 대화 중 Butler는 사용 중인 서버의 도구와 리소스 목록을 조회한 뒤, 필요한 도구를 호출하거나 리소스를 읽습니다.
  • 비활성 서버는 목록에서 빠지고 호출할 수 없습니다.
  • 작업마다 서버에 새로 연결하고 작업이 끝나면 연결을 닫습니다. stdio 서버는 작업할 때마다 프로세스를 새로 실행하므로 호출 사이에 서버 상태가 남지 않습니다.

연결 상태 확인과 문제 해결

연결 확인을 누르면 결과가 목록 위에 표시됩니다.

  • 성공 — <서버 ID>: tools <도구 수>, resources <리소스 수> 형식으로 표시됩니다.
  • 실패 — <서버 ID>: <오류 메시지> 형식으로 표시됩니다.

오류 메시지별로 다음을 확인합니다.

  • MCP server could not be started. — stdio 명령을 실행하지 못했습니다. 명령과 작업 폴더 경로를 확인하고, 명령은 절대 경로로 적습니다.
  • MCP server connection failed. — 서버와 MCP 연결을 맺지 못했습니다. stdio 서버라면 같은 명령을 터미널에서 실행해 바로 종료되지 않는지 확인합니다. HTTP 서버라면 Streamable HTTP와 SSE 중 서버가 지원하는 방식을 골랐는지 확인합니다.
  • MCP server connection timed out. — 10초 안에 연결하지 못했습니다. 서버가 실행 중인지, URL이 맞는지 확인합니다.
  • MCP operation timed out. — 연결은 됐지만 목록 조회가 10초 안에 끝나지 않았습니다.
  • MCP server request failed. — 연결 후 서버가 요청에 오류로 응답했습니다. 헤더의 인증 값을 확인합니다.
  • MCP server URL is invalid. — URL이 http:// 또는 https://로 시작하는지 확인합니다.
  • MCP server headers are invalid. — 헤더 이름이나 값에 쓸 수 없는 문자가 있는지 확인합니다.
  • MCP server credentials are unavailable. — 파일 출처의 파일을 읽지 못했습니다. 파일 권한을 확인합니다.

주의 사항

  • stdio 서버에는 Butler Agent의 환경 변수 중 HOME, LOGNAME, PATH, SHELL, TERM, USER만 전달됩니다. 서버에 필요한 다른 변수는 환경 변수에 직접 추가합니다. 같은 키를 추가하면 전달되는 값을 덮어씁니다.
  • stdio 서버의 오류 출력(stderr)은 Butler에 표시되지 않습니다. 원인을 찾으려면 같은 명령을 터미널에서 실행합니다.
  • ENV 참조는 Butler Agent가 시작될 때 받은 환경 변수에서 값을 찾습니다. 찾지 못한 변수나 없는 파일은 빈 값이 되어 그 키는 전달되지 않습니다.
  • 수정 폼에서 서버 ID를 바꿔도 반영되지 않습니다. ID를 바꾸려면 새로 추가한 뒤 기존 서버를 삭제합니다.
  • 삭제는 확인 없이 바로 적용됩니다.
  • OAuth 로그인은 지원하지 않습니다. 인증이 필요한 서버에는 헤더로 토큰을 넘깁니다.

관련 문서

MCP 서버로 쓰기butler mcp serve로 Butler를 다른 MCP 클라이언트에 연결합니다.설정 레퍼런스설정의 각 항목을 정리합니다.문제 해결준비 실패, 진단 복사, doctor 점검을 다룹니다.