LangSmith Tool Gateway란? 에이전트 툴 호출을 정책으로 통제하는 법

2026년 11월 19일 공개 베타로 나온 LangSmith Tool Gateway는 MCP 자격 증명을 대신 보관하고, 에이전트의 모든 툴 호출에 차단 또는 승인 정책을 적용한다.

영어 원문을 한국어로 옮긴 글이에요.Read in English

핵심 정리

  • LangChain은 2026년 11월 19일 LangSmith Tool Gateway를 Plus와 Enterprise 플랜에 공개 베타로 내놓았다.
  • 에이전트는 툴 키트 URL 하나로 여러 MCP 서버를 쓰고, 서버의 토큰이나 API 키를 직접 갖지 않는다.
  • 호출마다 사용자, 에이전트, 프로필, 워크스페이스 중 한 주체의 자격 증명을 쓴다.
  • 정책은 호출을 차단하거나 호출한 사람의 승인을 요구하고, 둘 다 해당하면 차단이 우선한다.
이 글의 차례
  1. LangSmith Tool Gateway는 무엇인가?
  2. 툴 호출은 게이트웨이 안에서 어떤 순서로 처리되나?
  3. 호출은 누구의 신원으로 나가나?
  4. 승인 정책과 차단 정책은 어떻게 동작하나?
  5. AI 에이전트를 쓰는 팀에는 무엇이 달라지나?
  6. Tool Gateway는 어떻게 설정하나?
  7. 한계와 남은 질문은?

LangSmith Tool Gateway는 AI 에이전트와 MCP 서버 사이에 놓이는 관리형 계층이다. 툴 자격 증명을 보관하고, 호출이 누구의 신원으로 나갈지 정하고, 모든 툴 호출에 차단 또는 승인 정책을 적용한다. LangChain은 2026년 11월 19일 LangSmith Agent Platform에서 이 기능을 공개 베타로 내놓았다 [1]. LangSmith Plus와 Enterprise 플랜에서 쓸 수 있다 [2].

LangSmith Tool Gateway는 무엇인가?

Tool Gateway는 MCP 서버를 등록하고, 계정을 연결하고, 툴 호출을 통제하는 곳을 하나로 모은다. 그래서 에이전트는 MCP URL 하나로 여러 툴에 닿는다. LangChain은 이를 "모든 에이전트 툴 호출의 자격 증명, 신원, 접근을 처리하는 관리형 툴 계층"이라고 설명한다 [1]. 모델 호출을 지출 한도, 대체 모델(fallback), 속도 제한, 민감 정보 가림(redaction)으로 관리하는 LLM Gateway가 이미 있고, Tool Gateway는 외부 툴 호출에서 같은 역할을 맡는다 [1].

문서는 기능을 세 묶음으로 나눈다. 접근(서버는 한 번 등록하고, 계정도 한 번 연결하고, 툴 키트마다 MCP URL 하나를 쓴다), 통제(차단 정책과 승인 정책), 가시성(툴 호출마다 트레이스 하나)이다 [2]. LangSmith Cloud의 GCP US, GCP EU, GCP APAC, AWS US 리전에서 돌아가고, Azure US 리전에서는 쓸 수 없다 [2].

출시 글은 호환 클라이언트로 LangChain, Deep Agents, Managed Deep Agents, Claude Code, Cursor를 꼽고, 게이트웨이가 "어떤 MCP 클라이언트와도 동작한다"고 적었다 [1]. 규모를 가늠할 사례로는 이름을 밝히지 않은 미국 대형 유통사를 든다. 이 회사 엔지니어링 팀은 매장 운영 에이전트용으로 MCP 서버 50개 이상을 만들었고, 서버들이 내놓는 툴은 1,000개가 넘는다 [1].

툴 호출은 게이트웨이 안에서 어떤 순서로 처리되나?

모든 호출은 같은 순서로 처리된다. 게이트웨이는 호출자를 확인하고, 차단 정책을 적용하고, 저장된 자격 증명을 붙이거나 호출자에게 연결을 요청하고, 승인 정책을 적용한 다음 호출을 넘기며, 추적이 켜져 있으면 트레이스를 남긴다 [2].

흐름도: 에이전트가 MCP URL 하나를 호출하면 Tool Gateway가 호출자를 확인하고, 차단 정책을 검사하고, 저장된 자격 증명을 붙이고, 승인 정책을 검사한 뒤 MCP 서버로 호출을 넘기고 트레이스를 남긴다.
Tool Gateway가 툴 호출 하나를 처리하는 순서(출처 [2], [3], [4]).

이 과정에서 인증이 세 번 따로 일어난다 [3].

  1. 호출자에서 게이트웨이로: 호출자는 개인 액세스 토큰, 서비스 키, LangSmith UI 세션, ID 공급자 토큰 중 하나로 LangSmith에 로그인한다.
  2. 자격 증명 주인: 게이트웨이는 호출자가 누구로서 행동하는지를 보고 저장된 자격 증명을 고른다.
  3. 게이트웨이에서 서버로: 게이트웨이는 OAuth 토큰이나 지정한 헤더에 담은 API 키로 MCP 서버에 인증한다. 공개 서버라면 인증하지 않는다.

핵심은 호출자가 서버의 토큰이나 API 키를 끝까지 갖지 않는다는 점이다 [3]. 프롬프트 인젝션을 당한 에이전트도 허용된 툴을 잘못 쓸 수는 있다. 하지만 유출할 서버 키는 처음부터 손에 없다.

호출은 누구의 신원으로 나가나?

호출 하나는 자격 증명 주인 하나만 쓴다. 주인은 사용자, 에이전트, 프로필, 워크스페이스 중 하나다 [3].

주인누가 연결하나언제 쓰이나
사용자각자 자기 계정을 연결호출이 해당 사용자로서 실행된다
에이전트관리자가 에이전트 인증으로 연결호출이 에이전트로서 실행된다
프로필관리자가 공용 자격 증명으로 한 번 연결호출이 프로필을 지정할 때(로그인한 사람이 없는 에이전트용)
워크스페이스워크스페이스 관리자가 API 키 하나로 연결호출자가 누구든 해당 서버로 가는 모든 호출

워크스페이스 자격 증명은 나머지보다 우선한다. 이 자격 증명이 저장돼 있는 동안에는 아무도 해당 서버에 다른 자격 증명을 연결할 수 없다 [3]. 사용자가 아직 계정을 연결하지 않았다면 호출은 로그인 링크를 돌려준다. URL 입력 요청(elicitation)을 지원하는 클라이언트는 링크를 화면에 보여 주고, 그렇지 않은 클라이언트는 링크와 함께 HTTP 428을 받는다. 에이전트나 프로필 자격 증명이 없으면 호출은 409를 돌려주고, 관리자가 자격 증명을 연결해야 한다.

승인 정책과 차단 정책은 어떻게 동작하나?

정책은 호출자가 무엇을 부를 수 있는지 정한다. 호출이 어느 엔드포인트로 들어오든 매 호출에 적용된다. 툴은 기본으로 허용되고, 정책은 호출을 차단하거나 실행 전에 승인을 요구한다 [3]. API에서는 이 두 효과를 FORBID와 REQUIRE_APPROVAL로 쓴다 [4].

  • 차단(FORBID): 호출은 실행되지 않고 tool_call_blocked 코드와 함께 403을 돌려준다.
  • 승인 요청(REQUIRE_APPROVAL): 폼 입력 요청을 지원하는 MCP 클라이언트에서 호출자가 승인해야만 호출이 실행된다. 거절하면 툴 오류가 돌아오고, 폼을 보여 줄 수 없는 클라이언트는 403을 받는다 [4].

호출이 두 종류에 모두 해당하면 차단이 이긴다. 에이전트 환경에 묶인 키라면 키의 정책과 에이전트의 정책을 모두 검사하고, 어느 한쪽이라도 차단하면 호출은 멈춘다. 정책을 바꾸면 다음 호출부터 바로 적용된다 [4].

정책에는 호출자와 툴을 적는다. 호출자로는 전체, 사용자, 사용자 그룹(Team), 서비스 키, 에이전트(AgentIdentity)를 지정할 수 있고, API로는 역할과 Fleet 에이전트도 지정할 수 있다. 툴은 <server-id>_<tool-name> 형식으로 적고, 서버 전체는 <server-id>_*, 내장 서버는 langsmith_<key>_<tool-name>, 모든 툴은 *로 적는다 [4]. workspace_id가 없는 정책은 조직의 모든 워크스페이스에 적용된다. 아래 요청 본문을 POST /v1/agent-policies로 보내면, 누구든 Linear 이슈를 만들기 전에 승인을 거쳐야 한다.

JSON
{
  "name": "approve-linear-issues",
  "description": "Approve each Linear issue before it is created",
  "effect": "REQUIRE_APPROVAL",
  "workspace_id": "<workspace-id>",
  "scope": {
    "principals": [{"type": "*", "id": "*"}],
    "actions": ["<linear-server-id>_save_issue"]
  }
}

조직 하나에는 조직 전체 정책을 최대 1,000개, 워크스페이스마다 정책을 100개까지 둘 수 있다. 정책 안의 목록 하나에는 항목을 100개까지 넣을 수 있다 [4]. 정책을 만들고, 바꾸고, 지우려면 서비스 키가 아니라 개인 액세스 토큰이나 LangSmith 세션이 필요하다. 변경 내역은 하나하나 조직의 감사 로그에 남는다.

AI 에이전트를 쓰는 팀에는 무엇이 달라지나?

팀 입장에서 가장 크게 바뀌는 점은 툴 접근을 정하는 자리다. 에이전트 코드나 각자의 로컬 MCP 설정이 아니라, 조직 단위의 정책 묶음 한곳에서 정한다. 팀 리더는 모든 팀원의 코딩 에이전트가 Linear를 읽게 하되 이슈를 만들 때는 확인을 거치게 할 수 있다. 이 규칙을 바꿔도 에이전트를 다시 배포할 필요가 없다.

설계할 때 챙길 점이 두 가지 있다. 첫째, 툴 키트는 에이전트에게 보이는 툴을 추려 줄 뿐이다. 문서는 키트가 "접근 통제 수단이 아니다"라고 밝히고, 차단된 툴도 키트 목록에는 그대로 나온다 [3][4]. 제한은 정책으로 하고, 키트는 툴 목록을 짧게 유지하는 데 쓴다. 둘째, 승인에는 클라이언트 앞에 앉은 사람이 필요하다. 그래서 Claude Code 세션처럼 사람이 함께하는 에이전트에 맞는다. 프로필로 돌아가는 백그라운드 에이전트에는 차단 규칙이나, 범위를 좁힌 키트와 차단 규칙의 조합이 필요하다.

트레이스는 에이전트 자신의 트레이스 안에 호출마다 툴, 서버, 신원, 결과, 소요 시간을 보여 준다. 툴에 보낸 데이터와 툴이 돌려준 데이터는 담지 않는다 [1][3]. 운영자는 트레이스에 고객 데이터를 쌓지 않고도 "어느 에이전트가 누구로서 어떤 툴을 불렀나"에 답할 수 있다.

Tool Gateway는 어떻게 설정하나?

준비물은 다음과 같다. Plus 또는 Enterprise 플랜, 워크스페이스 공용 서버와 키트를 만들 Workspace Admin 역할(Workspace Editor는 개인용만 추가할 수 있다), 개인 액세스 토큰, 그리고 X-Tenant-Id 헤더에 넣을 워크스페이스 ID다 [5]. 빠른 시작 문서는 네 단계로 진행한다.

  1. MCP 서버 추가: UI의 Tools 아래 MCP servers에서 추가하거나, name, upstream_url, scope, connection을 담아 POST /v1/managed-tools/servers를 호출한다. 연결 유형은 공개 서버면 none, 자동 또는 수동 OAuth면 oauth, 지정한 헤더에 API 키를 넣는 방식이면 secret이다 [6].
  2. 계정 연결: 서버마다 Connect를 누르거나, kits/me/connections/<server-id>에서 로그인 링크를 받는다 [5].
  3. 툴 키트 만들기: 서버 하나 또는 여러 개에서 툴을 고른다. 키트는 /v1/managed-tools/kits/<kit-id>/mcp 아래에 자기 MCP URL을 받는다.
  4. MCP 클라이언트를 키트 URL로 연결: Claude Code라면 빠른 시작 문서는 키트 URL과 X-Api-Key 헤더에 담은 LangSmith 키로 claude mcp add --transport http를 실행한다 [5].

3단계의 키트 본문에는 서버 ID와 툴 이름으로 툴을 나열한다.

JSON
{
  "name": "Quickstart kit",
  "scope": "workspace",
  "tools": [
    {"server_id": "<linear-server-id>", "tool_name": "list_issues"},
    {"server_id": "<linear-server-id>", "tool_name": "save_issue"},
    {"server_id": "<notion-server-id>", "tool_name": "notion-search"}
  ]
}

게이트웨이에는 키트 말고도 엔드포인트가 있다. kits/me/mcp는 호출자가 쓸 수 있는 툴을 모두 돌려주고, servers/<server-id>/mcp는 서버 하나만 다룬다 [3]. 내장 서버를 쓰면 설정 수고가 준다. GitHub, Gmail, Google Drive, Linear, Salesforce, Slack, Teams 같은 OAuth 서버, Exa와 Tavily 같은 API 키 서버, 자격 증명이 필요 없는 Parallel이 있다 [6]. MCP 프로토콜 버전 2026-07-28에서는 모든 원시 HTTP 요청에 Mcp-Method 헤더가 필요하고, tools/call 요청에는 툴 이름을 담은 Mcp-Name 헤더도 필요하다. 둘 중 하나라도 빠지면 400을 받는다. 2025-06-18 버전 요청에는 두 헤더 모두 넣지 않는다 [5].

한계와 남은 질문은?

게이트웨이에는 고정된 한도가 있다. 요청당 1 MB, 응답당 8 MB, MCP 서버가 응답을 시작하기까지 60초, 키트당 툴 10,000개, 초당 요청 100개(순간 최대 1,000개)다 [3].

제약의미
원격 서버만 지원HTTPS 위의 Streamable HTTP만 쓸 수 있다. 내부망 서버는 터널이 필요하다
출력은 그대로 전달게이트웨이는 툴 결과를 거르지 않는다. 결과는 믿을 수 없는 입력으로 다뤄야 한다
호출당 신원 하나한 호출에서 사용자 자격 증명과 프로필 자격 증명을 함께 쓸 수 없다
ID 공급자 토큰이 방식으로만 로그인한 호출자는 정책으로 막기 전까지 워크스페이스의 모든 서버와 키트에 닿는다
사용량 대시보드 없음트레이스와 감사 로그로 대신한다

이 내용은 동작 방식 문서에 나온다 [3]. Tool Gateway는 베타 단계라 한도와 동작이 바뀔 수 있다 [2].

2026년 11월 21일 현재 답이 나오지 않은 질문도 있다. 출시 글은 차단 정책과 감사 로그를 쓰려면 LangChain 팀에 문의하라고 하고, 감사 로그를 Enterprise 플랜 기능으로 분류한다 [1]. 반면 정책 문서는 플랜 조건을 밝히지 않는다 [4]. 자기 플랜에 어떤 통제 기능이 들어 있는지는 계정 담당팀에 확인해야 한다. 출시 글에는 툴 호출 가격이 나오지 않고, 호출자가 아닌 제3자가 승인하는 기능도 없다 [3].

자주 묻는 질문

LangSmith Tool Gateway는 정식 출시됐나?

아니다. LangChain은 2026년 11월 19일 LangSmith Plus와 Enterprise 플랜에 Tool Gateway를 공개 베타로 내놓았다. 리전은 GCP US, GCP EU, GCP APAC, AWS US이고 Azure US에서는 쓸 수 없다.

Tool Gateway에서 동료가 에이전트의 툴 호출을 승인할 수 있나?

할 수 없다. 승인 정책은 폼 입력 요청(elicitation)을 지원하는 MCP 클라이언트에서 호출한 당사자에게 확인을 받는다. 별도 검토자가 승인하는 기능은 없다. 사람이 지켜보지 않는 에이전트에는 문서가 차단 정책을 권한다.

툴 키트로 에이전트가 호출할 수 있는 툴을 제한할 수 있나?

키트만으로는 안 된다. 문서는 툴 키트가 접근 통제 수단이 아니라고 밝힌다. 키트는 에이전트에게 보이는 툴을 추려 줄 뿐이고, 차단된 툴도 키트 목록에는 그대로 나온다. 호출을 제한하려면 차단 정책이나 승인 정책을 써야 한다.

Tool Gateway에는 어떤 MCP 서버를 연결할 수 있나?

HTTPS 위에서 Streamable HTTP를 쓰는 원격 MCP 서버만 연결할 수 있다. 사설 네트워크 안의 서버는 터널 URL이 필요하다. GitHub, Slack, Linear, Exa, Tavily 같은 내장 서버도 있다.

Tool Gateway는 에이전트가 툴에 보낸 데이터를 기록하나?

기록하지 않는다. 트레이스에는 호출마다 툴, 서버, 신원, 결과, 소요 시간이 남지만, 툴에 보낸 데이터와 툴이 돌려준 데이터는 남지 않는다.

출처

  1. LangSmith Tool Gateway: Secure, governed tool use for agents — LangChain, 확인한 날
  2. Tool Gateway — LangChain Docs, 확인한 날
  3. How Tool Gateway works — LangChain Docs, 확인한 날
  4. Tool Gateway policies — LangChain Docs, 확인한 날
  5. Tool Gateway quickstart — LangChain Docs, 확인한 날
  6. Add MCP servers to Tool Gateway — LangChain Docs, 확인한 날