데이터 연결

사내 MCP 서버 연결

회사 안의 MCP 서버를 툴킷으로 등록해 웍스AI 에서 씁니다. 사내 MCP 를 회사 밖에 열지 않습니다.

대상 · Studio 관리자약 9분문서 내려받기

대상: 회사 관리자 · 사내 MCP 서버 담당자 선행 조건: 커넥터 v0.2.25 이상 설치 (커넥터 설치 가이드) · 사내망에서 돌고 있는 MCP 서버 함께 보실 것: 툴킷 사용법 · 웍스AI 에서 쓰기


이 기능이 하는 일

회사 안에서 이미 운영하고 계신 MCP 서버를 툴킷 하나로 등록합니다. 웍스AI 는 그 서버에 직접 붙지 않고, 다른 툴킷과 같은 MCP Hub 연결 주소로 그 서버의 도구를 씁니다.

웍스AI ─ MCP Hub ─ 커넥터 (회사 안) ─ 사내 MCP 서버
  • 사내 MCP 서버를 회사 밖에 열지 않으셔도 됩니다. Hub 와 사내 MCP 사이는 회사에 설치한 커넥터가 잇습니다.
  • 누가 어떤 도구를 썼는지 Studio 호출 로그에서 봅니다. 다른 툴킷과 같은 수준으로 남습니다(호출한 사람 · 시각 · 도구 · 성공 여부 · 걸린 시간). 응답 내용은 남기지 않습니다.
  • 어떤 도구를 AI 에 보여 줄지 관리자가 정합니다. 사내 MCP 에 새로 생긴 도구는 꺼진 채로 들어옵니다.
  • 호출한 사람을 사내 MCP 에 알려 줄 수 있습니다(선택). 사람마다 볼 수 있는 데이터가 다른 서버라면 켜 주세요.

1. 시작하기 전에

1-1. 받을 수 있는 MCP 서버

항목지원
연결 방식Streamable HTTP 만 받습니다
받지 않음stdio 방식 서버 · 예전 HTTP+SSE 방식(2024-11-05)만 지원하는 서버
버전MCP 2025-06-18 · 2025-03-26
쓰는 기능도구(tools) 만 씁니다
쓰지 않음resources · prompts · 서버가 먼저 보내는 요청(sampling · elicitation) · 알림
서버 인증인증 없음 · 고정 토큰 헤더 · Basic. 사내 MCP 의 OAuth 인증은 받지 않습니다

1-2. 주소는 "커넥터에서 닿는 주소" 입니다

MCP Hub 가 아니라 커넥터가 그 주소로 요청을 보냅니다. 커넥터 서버에서 열리는 사내 주소를 적어 주세요.

  • 예: http://mcp.internal:8080/mcp, https://mcp.example.local/mcp
  • http:// 또는 https:// 로 시작합니다. Studio 가 저장할 때 사내 MCP 툴킷 표시(mcp+http:// · mcp+https://)를 붙이므로 직접 붙이실 필요는 없습니다.
  • 커넥터 서버에서 curl -i <주소> 로 그 주소에 닿는지 먼저 확인하시면 등록이 빨라집니다. 응답 코드가 405 여도 닿은 것입니다(MCP 서버는 이런 요청을 받지 않을 수 있습니다).

1-3. 서버 인증 값은 커넥터 secrets 파일에

고정 토큰이나 Basic 비밀번호는 Studio 에 실제 값을 넣지 않고 ${변수이름} 으로만 적습니다. 실제 값은 커넥터 서버의 secrets 파일에 둡니다 — 툴킷 사용법 3절과 같은 방식입니다.


2. 등록하는 법

  1. Studio → 툴킷 → + 새 툴킷
  2. 종류에서 「사내 MCP」 를 고릅니다.
  3. 이름과 연결자(커넥터)를 고르고, MCP 서버 주소를 넣습니다 (1-2 참고).
  4. 인증 — 사내 MCP 가 요구하는 방식을 고릅니다 (없음 · 고정 토큰 · Basic).
  5. 호출한 사람 (선택 사항) — 「이 사내 MCP 가 호출한 사람을 알아야 하나요?」 에 답합니다 (3절 참고).
  6. 연결 확인 을 누릅니다. 커넥터를 거쳐 사내 MCP 의 도구 목록을 한 번 읽어 보고, 「연결했습니다. 도구 N개를 읽었습니다.」 처럼 결과를 보여 드립니다. 실패해도 만들기는 막지 않습니다.
  7. Toolkit 생성 을 누르면 도구 목록을 읽고 도구 탭으로 이동합니다.
  8. 도구 탭에서 쓸 도구의 「사용」 을 켭니다. 새 도구는 꺼진 채로 들어옵니다.
  9. 엔드포인트 탭에서 연결 주소를 발급해 웍스AI 에 등록합니다 — 웍스AI 에서 쓰기. 호출한 사람을 전달하는 툴킷이면 사용자 신원 확인 엔드포인트를 발급해 주세요 (3-2 참고).

[!NOTE] 주소와 연결자는 만든 뒤 바꿀 수 없습니다 다른 서버나 다른 커넥터는 도구 목록 전체가 다를 수 있습니다. 바꾸려면 툴킷을 새로 만들어 주세요. 인증과 호출한 사람 전달은 설정 탭에서 바꿀 수 있습니다.


3. 호출한 사람 전달 (선택)

웍스AI 에서 도구를 부른 사람의 이메일 또는 사번을 정한 이름의 헤더에 실어 사내 MCP 에 보냅니다. 값은 Hub 가 채우고, AI 는 이 값을 바꿀 수 없습니다.

3-1. 켤지 정하는 기준

  • 켜 주세요 — 사내 MCP 가 사람마다 다른 데이터를 돌려주거나, 사람마다 권한을 따로 확인하는 경우.
  • 끄셔도 됩니다 — 누가 불러도 같은 결과를 주는 서버(공통 코드 조회, 사내 규정 검색 등). 꺼 두면 어느 엔드포인트로 들어온 호출이든 신원 없이 사내 MCP 로 보냅니다.

헤더 이름(예: X-User-Email)과 보낼 값(이메일 · 사번)을 정합니다. Authorization 처럼 예약된 이름이나 이 툴킷의 인증에 쓰는 이름은 쓸 수 없고, 화면이 바로 알려 드립니다. 만든 뒤에는 설정 탭의 「호출한 사람」 칸에서 바꿉니다.

3-2. 켜면 사용자 신원 확인 엔드포인트로만 부를 수 있습니다

[!IMPORTANT] HTTP 툴킷과 다릅니다 호출한 사람 전달을 켠 사내 MCP 툴킷은 사용자 신원 확인 엔드포인트(웍스AI 가 로그인한 사람을 확인해 주는 연결)로 들어온 호출만 사내 MCP 로 보냅니다. 고정 토큰(API Key) · OAuth (per-user) 엔드포인트로 들어온 호출은 사내 MCP 로 보내지 않고 거절합니다.

HTTP 툴킷은 이런 호출을 헤더 없이 보내지만, 사내 MCP 툴킷은 "사람을 모르는 호출" 이 사내 MCP 에 닿지 않게 했습니다. 설정 탭의 엔드포인트 표에서 각 엔드포인트가 「호출이 거절됩니다」 인지 미리 보실 수 있습니다.

사번을 고르셨는데 사번이 등록되지 않은 사람의 호출도 사내 MCP 로 보내지 않습니다.

3-3. 사내 MCP 가 할 일 — 커넥터에서 온 요청만 받기 (필수)

[!WARNING] 이 헤더는 서명이 없는 보통 헤더입니다 사내 MCP 에 직접 닿을 수 있는 사람은 누구나 같은 이름의 헤더를 지어 넣어 다른 사람인 척할 수 있습니다. 사내 MCP 는 아래 둘 중 하나로 커넥터를 거쳐 온 요청만 받도록 준비해 주세요.

  • 커넥터 서버에서 온 요청만 받기 — 방화벽 · 접근 목록으로 커넥터 서버 주소만 허용합니다.
  • 고정 토큰으로 확인하기 — 이 툴킷의 인증을 「고정 토큰」 으로 정하고, 사내 MCP 는 그 토큰이 맞는 요청만 받습니다. 토큰은 커넥터 secrets 파일에만 둡니다.

둘 다 하시면 더 안전합니다. 서명된 신원을 보내는 방식은 다음 단계로 준비 중입니다.

신원은 이 헤더에서만 읽어 주세요. 도구 인자에 같은 이름의 값이 있어도 그 값은 AI 가 채운 것입니다.


4. 도구 확인과 다시 읽기

도구의 이름 · 설명 · 입력 항목은 사내 MCP 가 정한 그대로 AI 에 보여 드립니다. 사내 MCP 가 주는 안내문 (instructions)도 그대로 AI 에 전달합니다.

4-1. 「다시 읽기」

사내 MCP 의 도구가 바뀌었으면 도구 탭의 「다시 읽기」 를 눌러 주세요. Hub 는 자동으로 다시 읽지 않습니다. 결과는 「새 도구 N개 · 바뀐 도구 N개 · 사라진 도구 N개」 로 알려 드립니다.

바뀐 것「사용」표시하실 일
새로 생긴 도구꺼짐「새 도구」설명을 확인하고 쓸 도구만 켭니다
위험 표시(annotations)가 바뀐 도구꺼짐「바뀐 도구」확인한 뒤 다시 켭니다
사라졌다가 같은 이름으로 다시 나타난 도구꺼짐「새 도구」새 도구와 같이 확인한 뒤 켭니다
설명이나 입력 항목만 바뀐 도구사용 상태 그대로「바뀐 도구」확인한 뒤 「확인」 을 누릅니다
사내 MCP 에서 사라진 도구목록에서 빠집니다—없음

관리자가 켜지 않은 도구는 AI 에게 보이지 않고, 불려도 사내 MCP 로 보내지 않습니다.

4-2. 읽을 수 있는 크기

  • 한 툴킷에 도구는 500개까지 둘 수 있습니다. 넘으면 다시 읽기가 실패하고 지금 저장된 도구는 그대로입니다.
  • 이름이 128자를 넘는 도구, 정의 하나가 32KB 를 넘는 도구, 형식이 맞지 않는 도구, 앞의 도구와 이름이 겹치는 도구는 읽지 않습니다. 다시 읽기 결과에 「읽지 못한 도구 N개」 로 그 개수를 알려 드립니다.
  • 도구 정의 전체가 1MB 를 넘으면 저장하지 않고, 지금 저장된 도구는 그대로입니다.

4-3. 이 툴킷에서 쓰지 않는 기능

  • 도구 이름 · 설명 바꾸기와 AI 설명 제안 — 이름과 설명은 사내 MCP 담당자가 관리합니다.
  • 도구 노출 방식(검색형 · 핵심 도구만 노출) — 켠 도구를 모두 AI 에 보여 드립니다.
  • 엔드포인트 테스트 버튼 — 대신 체험 탭으로 시험합니다 (5절).

5. 체험 탭으로 시험하기

툴킷의 체험 탭에서 웍스AI 없이 바로 도구를 불러 볼 수 있습니다.

  • 호출한 사람 전달을 켠 툴킷은 체험하는 관리자 본인의 이메일을 실어 보냅니다. 다른 사람의 값으로 시험할 수는 없습니다.
  • 그러려면 Studio 에 웍스AI 로 로그인하셔야 합니다. 이 기능이 나오기 전에 로그인해 두신 화면이라면 로그아웃한 뒤 다시 로그인해 주세요. 그렇지 않으면 「웍스AI 로 다시 로그인해야 시험할 수 있습니다. 로그아웃한 뒤 웍스AI 로 로그인해 주세요.」 가 보이고 사내 MCP 로 보내지 않습니다. 이 기능이 나오기 전에 로그인해 두신 화면이라면 로그아웃한 뒤 웍스AI 로 다시 로그인해 주세요.
  • 사번을 보내도록 정한 툴킷은 체험에서 시험할 수 없습니다. 웍스AI 대화에서 시험해 주세요.
  • 호출한 사람 전달을 끈 툴킷은 신원 없이 부릅니다.

6. 호출 방식과 한계

  • 호출마다 새로 연결합니다. 사내 MCP 와의 세션은 호출 한 번이 끝나면 닫습니다. 세션에 상태를 기억해 두고 다음 호출에서 이어 쓰는 서버는 그 상태가 이어지지 않습니다. 대신 한 사람의 세션이 다른 사람의 호출에 섞이는 일이 없습니다.
  • 호출 전체에 시간 제한이 있습니다. 기본 60초이고, 설정 탭의 「응답 대기 시간」 에서 최대 180초까지 늘릴 수 있습니다. 연결 · 도구 호출 · 응답을 모두 합친 시간입니다.
  • 결과를 보낸 뒤 응답을 닫아 주세요. 스트림(SSE)으로 답하는 서버가 결과를 보낸 뒤에도 연결을 열어 두면 그 호출은 시간 초과로 끝납니다.
  • 사내 MCP 가 돌려준 도구 오류는 그대로 AI 에 전달합니다. 연결 실패 같은 오류는 사유만 호출 로그에 남깁니다.
  • 일시 중지는 다른 툴킷과 같습니다. 툴킷을 일시 중지하면 사내 MCP 로 가는 호출이 바로 멈춥니다.

7. 문제가 생기면

화면에 보이는 안내확인하실 것
커넥터를 거쳐 사내 MCP 에 닿지 못했습니다커넥터가 켜져 있는지, 커넥터 서버에서 주소가 열리는지 (1-2)
사내 MCP 가 요청을 받지 않았습니다주소와 인증 설정, secrets 파일의 변수 이름. 주소가 다른 서버로 넘기면 커넥터가 따라가지 않으니 최종 주소를 넣습니다
사내 MCP 의 응답을 읽지 못했습니다주소가 MCP 서버의 주소인지, Streamable HTTP 와 지원 버전을 쓰는지 (1-1)
사내 MCP 와 연결을 맺지 못했습니다사내 MCP 담당자와 서버의 세션 처리를 확인해 주세요
도구가 너무 많아 읽지 못했습니다한 툴킷에는 도구를 500개까지 둘 수 있습니다. 서버를 나누어 등록해 주세요
이 주소는 MCP Hub 의 연결 주소입니다사내 MCP 주소에 MCP Hub 엔드포인트 주소를 넣으셨습니다. 사내 MCP 서버의 주소를 넣어 주세요
웍스AI 로 다시 로그인해야 시험할 수 있습니다Studio 를 로그아웃하고 웍스AI 로 다시 로그인 (5절)
웍스AI 에서 부르면 거절됩니다웍스AI 에 등록한 연결이 사용자 신원 확인 엔드포인트인지 (3-2)

8. 문의

  • 등록 · 호출이 안 될 때: WRKS 담당자에게 툴킷 이름과 호출 시각을 알려 주세요. 호출 로그로 확인해 드립니다.
  • 사내 MCP 서버의 도구 · 인증 · 접근 제한: 사내 MCP 서버 담당자와 함께 확인해 주세요.