LangSmith Remote MCP

OAuth를 통해 MCP 호환 클라이언트를 LangSmith에 연결하거나, LangSmith API 키로 프로그래매틱 클라이언트를 인증하는 방법을 알려드릴게요.

LangSmith Remote MCP는 LangSmith가 호스팅하는 Model Context Protocol(MCP) 서버입니다. 별도 배포 없이 독립 실행형 LangSmith MCP Server와 동일한 도구(대화 기록, 프롬프트, 실행과 트레이스, 데이터셋, 실험, 청구)를 노출합니다. 인터랙티브 MCP 클라이언트는 API 키나 헤더 구성 없이 OAuth로 연결하고, 프로그래매틱 클라이언트는 X-Api-Key 헤더를 통해 LangSmith API 키로 인증할 수 있습니다.

Remote MCP는 모든 LangSmith Cloud 리전, BYOC 데이터 플레인, 그리고 v0.16 이상을 실행하는 셀프 호스팅 LangSmith 배포에서 사용할 수 있습니다(셀프 호스팅은 추가로 서명 JWKS 구성 필요 — 셀프 호스팅 LangSmith 참고). 이전 버전의 셀프 호스팅 배포는 계속 독립 실행형 LangSmith MCP Server를 사용해야 합니다.

출처: 문서

본문

엔드포인트

LangSmith Cloud:

Region	URL
GCP US	`https://api.smith.langchain.com/mcp`
GCP EU	`https://eu.api.smith.langchain.com/mcp`
GCP APAC	`https://apac.api.smith.langchain.com/mcp`
AWS US	`https://aws.api.smith.langchain.com/mcp`

서버는 동일 호스트의 /.well-known/oauth-authorization-server에서 RFC 8414를 통해 나머지 OAuth 메타데이터를 발견하므로, 규격을 준수하는 MCP 클라이언트는 위 URL만 필요합니다.

셀프 호스팅 LangSmith:

https://<your-langsmith-host>/api/mcp. 여기서 <your-langsmith-host>는 LangSmith 인스턴스의 호스트 이름입니다.

BYOC:

https://<data_plane_url>/api/mcp. 여기서 <data_plane_url>은 BYOC 데이터 플레인의 URL입니다.

인증

Remote MCP는 두 가지 인증 방식을 지원합니다. 인터랙티브 MCP 클라이언트(Claude Code, Cursor 등)에는 OAuth를, 브라우저 기반 로그인을 완료할 수 없는 프로그래매틱 또는 헤드리스 클라이언트에는 API 키를 사용하세요.

OAuth

동적 클라이언트 등록(RFC 7591)이 있는 OAuth 2.1은 인터랙티브 클라이언트의 기본입니다. 호환 MCP 클라이언트는 첫 사용 시 자동으로 등록됩니다 — 프로비저닝할 클라이언트 ID도, 관리할 API 키도 없습니다.

등록 후:

클라이언트는 브라우저에서 인증 URL을 엽니다.
동의합니다.
클라이언트는 토큰을 저장하고 연결을 완료합니다.

이후 연결에서는 재인증이 필요하지 않습니다.

API 키: 브라우저 기반 로그인을 완료할 수 없는 프로그래매틱 또는 헤드리스 클라이언트는 X-Api-Key 헤더를 통해 인증할 수 있습니다. 워크스페이스 범위의 API 키를 사용하세요.

LangSmith CLI

LangSmith CLI는 동일한 OAuth 서버에 대해 인증하므로, langsmith auth login은 OAuth 기기 플로우로 로그인합니다 — API 키 불필요:

# LangSmith Cloud
langsmith auth login

# Self-hosted (point at your instance's /api base)
langsmith auth login --api-url https://<your-langsmith-host>/api

CLI는 활성화 URL을 출력합니다. 열고 승인하면 CLI가 로그인을 완료하고 토큰을 프로필별로 ~/.langsmith/config.json에 저장합니다. 그런 다음 Remote MCP 서버와 동일한 프로젝트, 트레이스, 실행, 데이터셋, 실험, 스레드에 대해 작동합니다.

AI SDK

AI SDK에서 프로그래매틱 사용을 위해 X-Api-Key 헤더와 내장 http(Streamable HTTP) 전송으로 API 키를 인증합니다:

import { createMCPClient } from "@ai-sdk/mcp";

const client = await createMCPClient({
  transport: {
    type: "http",
    url: "https://api.smith.langchain.com/mcp",
    headers: { "X-Api-Key": process.env.LANGSMITH_API_KEY! },
  },
});

const tools = await client.tools();

tools를 streamText 또는 generateText에 직접 전달하세요. Remote MCP는 상태 비저장이며 표준 Streamable HTTP 전송으로 JSON으로 응답하므로 내장 전송이 그대로 동작합니다 — 커스텀 전송이 필요 없습니다.

기타 클라이언트

Streamable HTTP 전송을 지원하는 모든 MCP 클라이언트는 위 URL만으로 연결할 수 있습니다 — 동적 클라이언트 등록이 있는 OAuth 2.1 또는 X-Api-Key 헤더의 LangSmith API 키를 사용합니다.

알려진 클라이언트 비호환성

참고: OpenAI Codex CLI는 LangSmith Remote MCP와 동작하지 않습니다. Codex는 OAuth 플로우 중 MCP 권한 부여 스펙이 요구하는 RFC 8707 resource 파라미터를 생략하므로 로그인이 성공하는 것처럼 보이지만 발급된 토큰이 LangSmith MCP에 바인딩되지 않아 initialize가 auth-required 오류로 실패합니다. 두 개의 업스트림 이슈가 Codex의 토큰 교환과 authorize 요청에 영향을 줍니다 (openai/codex#20729 및 openai/codex#13891 참고). 그동안 Codex에서 LangSmith CLI를 사용하세요. LangSmith CLI는 네이티브 OAuth 로그인과 함께 MCP 서버와 동일한 프로젝트, 트레이스, 실행, 데이터셋, 실험, 스레드를 지원합니다.

사용 가능한 도구

Remote MCP는 독립 실행형 서버와 동일한 도구 표면을 노출합니다:

대화와 스레드: get_thread_history
프롬프트 관리: list_prompts, get_prompt_by_name, push_prompt
트레이스와 실행: fetch_runs, list_projects
데이터셋과 예제: list_datasets, list_examples, read_dataset, read_example, create_dataset, update_examples
실험과 평가: list_experiments, run_experiment
청구: get_billing_usage

파라미터와 페이지네이션 세부정보는 독립 실행형 서버 레퍼런스를 참고하세요 — 두 서버 모두 동일한 도구 구현을 공유합니다.

재인증

클라이언트가 세션을 잃으면(예: LangSmith 계정에서 접근을 취소한 경우, 또는 refresh 토큰이 무효화된 경우) 클라이언트에서 재인증을 트리거하세요:

Claude Code: /mcp 실행, langsmith 선택, re-authenticate 선택.
Cursor: MCP 설정에서 서버 비활성화 후 재활성화.
기타 클라이언트: 클라이언트의 MCP 설정 UI 참조.

셀프 호스팅 LangSmith

v0.16 이상의 셀프 호스팅 LangSmith 배포는 https://<your-langsmith-host>/api/mcp에서 Remote MCP를 노출합니다. 활성화되면 인증과 도구 표면은 LangSmith Cloud와 동일합니다.

Remote MCP 활성화

Remote MCP와 그 OAuth 인증 서버는 config.hostname이 설정되면 자동으로 연결되지만, 서명 JWKS를 제공하기 전까지는 비활성(404) 상태로 유지됩니다. 이것이 LangSmith Cloud가 대신 처리하는 유일한 구성입니다. 활성화하려면:

Ed25519(OKP) JWKS 생성. RSA 키는 거부됩니다. 예를 들어 step으로:

step crypto jwk create /dev/null /tmp/jwk.json --kty OKP --crv Ed25519 --no-password --insecure -f
jq -c '{keys:[.]}' /tmp/jwk.json   # wrap the single key in a JWKS

차트에 제공 — config.signingJwks로(차트 시크릿에 저장) 또는 기존 시크릿의 langsmith_signing_jwks 키로:
```
config:
  hostname: "your-langsmith-host"
  signingJwks: |
    {"keys":[ ... ]}
```
경고: commonEnv 또는 extraEnv로 LANGSMITH_SIGNING_JWKS를 직접 설정하지 마세요 — 차트가 이미 시크릿에서 연결하며, 수동 복사는 중복 환경 변수 오류로 설치가 실패합니다. config.signingJwks 또는 config.existingSecretName을 사용하세요.

업그레이드 후 OAuth 발견 엔드포인트와 /api/mcp가 활성화됩니다. 다음으로 확인하세요:

curl https://<your-langsmith-host>/api/.well-known/oauth-protected-resource/mcp

이전 버전의 배포의 경우 자체 환경에서 독립 실행형 LangSmith MCP Server를 실행하고 LANGSMITH_ENDPOINT를 셀프 호스팅 인스턴스로 지정하세요.

더 알아보기

LangSmith MCP Server — 독립 실행형 서버 참조.
LangSmith CLI — OAuth 로그인을 사용한 CLI 도구.