Langfuse MCP Server

Langfuse MCP Server

Langfuse에는 네이티브 Model Context Protocol(MCP) 서버가 포함되어 있어 AI 어시스턴트와 에이전트가 내 Langfuse 데이터와 프로그래매틱하게 상호작용할 수 있습니다. 이 문서는 Langfuse MCP 서버의 설정 방법(인증 헤더, 클라이언트별 등록)과 주요 도구들을 설명해요. 데이터 플랫폼용 인증 MCP 서버이며, 문서용 공개 MCP 서버와는 구분됩니다.

출처: 문서

본문

Langfuse에는 네이티브 Model Context Protocol(MCP) 서버가 포함되어 있어 AI 어시스턴트와 에이전트가 내 Langfuse 데이터와 프로그래매틱하게 상호작용할 수 있게 해줍니다.

새 도구에 대한 피드백이나 아이디어가 있다면 GitHub에서 공유 해 주세요.

CLI 도구를 설치하고 bash 명령을 실행할 수 있는 환경에서 AI 에이전트를 돌린다면, MCP 서버 대신 Langfuse Agent Skill 을 사용할 것을 권장합니다.

이것은 Langfuse 데이터 플랫폼용 인증 MCP 서버입니다. Langfuse 문서용 공개 MCP 서버도 있습니다 (docs).

MCP 참조(MCP Reference)

MCP Reference 는 현재 Langfuse MCP 서버, 설정 스니펫, 도구, 입력 스키마, 생성된 요청 예시의 표준 소스입니다.

기본적으로 읽기와 쓰기 도구가 모두 제공됩니다. 읽기 전용 도구만 사용하려면 MCP 클라이언트에 허용 목록(allowlist)을 구성해 쓰기 작업 접근을 제한하세요. 전체 도구 목록은 MCP Reference 를 참고하세요.

설정(Set up)

Langfuse MCP 서버는 각 API 키가 특정 프로젝트로 범위가 지정되는 무상태(stateless) 아키텍처를 사용합니다. 다음 구성으로 MCP 서버에 연결하세요:

• Endpoint: https://cloud.langfuse.com/api/public/mcp (EU)
• Endpoint: https://us.cloud.langfuse.com/api/public/mcp (US)
• Endpoint: https://jp.cloud.langfuse.com/api/public/mcp (Japan)
• Endpoint: https://hipaa.cloud.langfuse.com/api/public/mcp (HIPAA)
• Endpoint: https://your-domain.com/api/public/mcp (Self-hosted)
• Transport: streamableHttp
• Authentication: Basic Auth via authorization header

역방향 프록시 배포에서 Langfuse Assistant 워커가 내부 Docker/Kubernetes 호스트 이름으로 MCP를 호출할 때는 공개 Host 헤더가 보존되는지 확인하거나, MCP 엔드포인트가 허용하는 정확한 추가 호스트 이름/오리진의 쉼표 구분 목록으로 LANGFUSE_MCP_ALLOWED_HOSTS를 설정하세요. 그렇지 않으면 403 오류가 발생합니다.

인증 헤더 가져오기

프로젝트 설정으로 이동해 프로젝트 범위 API 키를 만들거나 복사하세요:

• Public Key: pk-lf-...
• Secret Key: sk-lf-...

자격 증명을 base64 형식으로 인코딩합니다:

echo -n "«redacted:pk-lf-…»:«redacted:sk-…»" | base64

클라이언트 설정

단일 명령으로 Langfuse MCP 서버를 등록하세요. {your-base64-token}을 내 인코딩된 자격 증명으로 바꾸세요:

Claude Code:

# Langfuse Cloud (EU)
claude mcp add --transport http langfuse https://cloud.langfuse.com/api/public/mcp \
    --header "Authorization: Basic {your-base64-token}"

# Langfuse Cloud (US)
claude mcp add --transport http langfuse https://us.cloud.langfuse.com/api/public/mcp \
    --header "Authorization: Basic {your-base64-token}"

# Langfuse Cloud (Japan)
claude mcp add --transport http langfuse https://jp.cloud.langfuse.com/api/public/mcp \
    --header "Authorization: Basic {your-base64-token}"

# Langfuse Cloud (HIPAA)
claude mcp add --transport http langfuse https://hipaa.cloud.langfuse.com/api/public/mcp \
    --header "Authorization: Basic {your-base64-token}"

# Self-Hosted (HTTPS required)
claude mcp add --transport http langfuse https://your-domain.com/api/public/mcp \
    --header "Authorization: Basic {your-base64-token}"

# Local Development
claude mcp add --transport http langfuse http://localhost:3000/api/public/mcp \
    --header "Authorization: Basic {your-base64-token}"

Claude Code에 list all prompts in the project를 요청해 연결을 확인하세요. Claude Code는 listPrompts 도구를 사용해 프롬프트 목록을 반환해야 합니다.

Codex: ~/.codex/config.toml에 MCP 서버를 추가하세요(EU 예시):

[mcp_servers.langfuse]
url = "https://cloud.langfuse.com/api/public/mcp"
http_headers = { "Authorization" = "Basic {your-base64-token}" }

US/Japan/HIPAA/self-hosted 리전은 url을 각각 https://us.cloud.langfuse.com, https://jp.cloud.langfuse.com, https://hipaa.cloud.langfuse.com, https://your-domain.com의 /api/public/mcp로 바꾸면 됩니다. Codex를 재시작하고 codex mcp list를 실행해 서버가 등록됐는지 확인하세요. 그다음 list all prompts in the project를 요청해 확인합니다.

Cursor: Cursor Settings(Cmd/Ctrl + Shift + J)를 열고, Tools & Integrations 탭으로 이동한 뒤 **"Add Custom MCP"**를 클릭해 MCP 서버 구성을 추가하세요(EU 예시):

{
  "mcp": {
    "servers": {
      "langfuse": {
        "url": "https://cloud.langfuse.com/api/public/mcp",
        "headers": {
          "Authorization": "Basic {your-base64-token}"
        }
      }
    }
  }
}

US/Japan/HIPAA/self-hosted 리전은 url만 바꾸면 됩니다. 파일을 저장하고 Cursor를 재시작하면 서버가 MCP 설정에 활성(green dot) 상태로 표시됩니다.

Pi: Pi 는 내장 MCP 지원이 없으므로 커뮤니티 유지 관리 pi-mcp-adapter 확장을 사용하세요. 단일 프록시 도구를 통해 MCP 서버를 Pi에 노출합니다.

확장을 설치하고 Pi를 재시작하세요:

pi install npm:pi-mcp-adapter

~/.pi/agent/mcp.json에 Langfuse MCP 서버를 추가하세요(EU 예시):

{
  "mcpServers": {
    "langfuse": {
      "url": "https://cloud.langfuse.com/api/public/mcp",
      "headers": {
        "Authorization": "Basic {your-base64-token}"
      }
    }
  }
}

US/Japan/HIPAA/self-hosted 리전은 url만 바꾸면 됩니다. Pi를 재시작하고 list all prompts in the project를 요청해 연결을 확인하세요.

• Transport: streamableHttp
• Authentication: Basic Auth via authorization header — Authorization: Basic {your-base64-token}

논리적 루트 observations 필터링

observation 도구는 논리적 루트와 물리적 부모 관계를 구분합니다:

• listObservations는 선택적 불리언 isRootObservation 필터를 받습니다. true로 설정하면 물리적 부모가 없는 observation이나 SDK가 애플리케이션 루트로 명시적으로 표시한 observation을 매칭합니다.
• 물리적 부모 필터링은 별도로 유지됩니다. 애플리케이션 루트 observation은 물리적 부모가 있어도 isRootObservation: true와 매칭될 수 있습니다.
• isRootObservation은 listObservations가 반환하는 기본 observation 필드에 포함됩니다.
• getObservationFilterValues는 필터 값 컬럼으로 isRootObservation을 지원하므로 논리적 루트 값을 발견하고 다른 observation 필터와 결합할 수 있습니다.

전체 도구 스키마와 요청 예시는 MCP Reference 를 참고하세요.

피드백(Feedback)

Langfuse MCP 서버에 대한 경험을 듣고 싶습니다. 피드백, 아이디어, 사용 사례를 GitHub Discussion 에서 공유해 주세요.

관련 문서(Related Documentation)

• MCP Reference — MCP 서버, 설정 스니펫, 도구, 스키마, 요청 참조
• Agentic Prompt Management — 에이전트로 프롬프트 조회·생성·마이그레이션·업데이트
• Prompt Management Overview — Langfuse 프롬프트 관리 알아보기
• Public API — 프로그래매틱 접근용 REST API
• Langfuse Agent Skill — 코딩 에이전트에서 Langfuse 기능 사용
• Langfuse for Agents — 코딩 에이전트용 스킬, CLI, MCP 서버 개요

더 알아보기 (Learn more)

• 출처 문서: Langfuse MCP Server