Skip to content

Commit 834ba6f

Browse files
FroeMicclaudemarcklingen
authored
docs: native MCP server documentation (#2325)
* docs: update MCP server documentation for native implementation Add comprehensive documentation for the native MCP server built into Langfuse at /api/public/mcp, replacing the previous external mcp-server-langfuse repository approach. Changes: - Add changelog post announcing native MCP server with write operations - Create new general MCP server page under api-and-data-platform/features - Update prompt management MCP page to reflect native implementation - Add MCP Server card to api-and-data-platform overview Key updates: - Remove external GitHub clone/build instructions - Add BasicAuth authentication setup - Document all 5 tools (getPrompt, listPrompts, createTextPrompt, createChatPrompt, updatePromptLabels) - Update client setup for HTTP transport (Claude Code, Cursor) - Add example workflows and use cases - Highlight audit logging and stateless architecture 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]> * docs: add MCP server screenshot to changelog and docs Replace video embed with screenshot showing all 5 MCP tools in Claude Code. The image clearly displays getPrompt, listPrompts, createTextPrompt, createChatPrompt, and updatePromptLabels with read-only annotations. * docs: remove duplicate image from changelog The ogImage in frontmatter already displays in ChangelogHeader, so remove the duplicate Frame element. * docs: improve MCP documentation based on feedback Changes: - Remove 'automatic audit logging' mention from changelog - Simplify 'Simplified Setup' to 'Setup' in changelog - Simplify Architecture section to focus on project-scoped API keys - Add warning about read/write tools and allowlist configuration - Remove Tool Annotations section (implementation detail) - Add Feedback sections linking to GitHub Discussion #10605 - Replace duplicated setup instructions with link to main guide - Remove redundant audit logging mentions These changes make the docs more user-focused and less technical. * docs: add feedback section to changelog Add dedicated Feedback section in changelog to encourage users to share their experience in GitHub Discussion #10605. * note on old mcp server * changelog edits * edits --------- Co-authored-by: Claude <[email protected]> Co-authored-by: Marc Klingen <[email protected]>
1 parent 8267771 commit 834ba6f

File tree

6 files changed

+382
-105
lines changed

6 files changed

+382
-105
lines changed

‎pages/changelog/2025-02-16-mcp-server-update.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,10 @@ import { ChangelogHeader } from "@/components/changelog/ChangelogHeader";
1111

1212
<ChangelogHeader />
1313

14+
<Callout type="info">
15+
**Update (November 2025):** This MCP server has been superseded by our [native MCP server](/changelog/2025-11-20-native-mcp-server) using StreamableHttp, which includes write operations and requires no external setup.
16+
</Callout>
17+
1418
Short demo of the MCP Server in action in Claude Desktop.
1519

1620
<iframe

‎pages/changelog/2025-11-20-native-mcp-server.mdx‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
date: 2025-11-20
3+
title: Hosted MCP Server for Langfuse Prompt Management
4+
description: Langfuse now includes a native Model Context Protocol (MCP) server with write capabilities, enabling AI agents to fetch and update prompts directly.
5+
author: Michael
6+
ogImage: /images/changelog/2025-11-20-native-mcp-server.png
7+
---
8+
9+
import { ChangelogHeader } from "@/components/changelog/ChangelogHeader";
10+
11+
<ChangelogHeader />
12+
13+
We're excited to announce that Langfuse now includes a **native MCP server** built directly into the platform. We release it with support for [Prompt Management](/docs/prompt-management/overview) and will extend it to the rest of the Langfuse data platform in the future.
14+
15+
Our previous Prompt MCP server ([changelog](/changelog/2025-02-16-mcp-server-update)) was a node package. The new one uses `StreamableHttp` to communicate with the Langfuse API directly, no need for building or installing any external dependencies.
16+
17+
## What's New
18+
19+
The native MCP server is available at `/api/public/mcp` and provides five tools for comprehensive prompt management:
20+
21+
**Read Operations:**
22+
23+
- `getPrompt` - Fetch specific prompts by name, label, or version
24+
- `listPrompts` - Browse all prompts with filtering and pagination
25+
26+
**Write Operations:**
27+
28+
- `createTextPrompt` - Create new text prompt versions
29+
- `createChatPrompt` - Create new chat prompt versions (OpenAI-style messages)
30+
- `updatePromptLabels` - Manage labels across prompt versions
31+
32+
## Setup
33+
34+
Simply configure your MCP client with BasicAuth credentials:
35+
36+
```bash
37+
# Claude Code - one command
38+
claude mcp add --transport http langfuse https://cloud.langfuse.com/api/public/mcp \
39+
--header "Authorization: Basic {your-base64-token}"
40+
```
41+
42+
The native server uses a stateless architecture, ensuring clean separation between projects and reliable operation across all deployment types (Cloud, self-hosted, or local development).
43+
44+
See [documentation](/docs/api-and-data-platform/features/mcp-server) for more details.
45+
46+
## Feedback
47+
48+
We'd love to hear about your experience with the Langfuse MCP server. Share your feedback, ideas, and use cases in our [GitHub Discussion](https://github.com/orgs/langfuse/discussions/10605).
49+
50+
## Get Started
51+
52+
- [MCP Server Documentation](/docs/api-and-data-platform/features/mcp-server) - Complete setup guide
53+
- [Prompt Management with MCP](/docs/prompt-management/features/mcp-server) - Prompt-specific workflows

‎pages/docs/api-and-data-platform/features/mcp-server.mdx‎

Lines changed: 261 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,261 @@
1+
---
2+
title: Langfuse MCP Server
3+
sidebarTitle: MCP Server
4+
description: Native Model Context Protocol (MCP) server for Langfuse, enabling AI assistants to interact with your Langfuse data programmatically.
5+
---
6+
7+
# Langfuse MCP Server
8+
9+
Langfuse includes a native [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that enables AI assistants and agents to interact with your Langfuse data programmatically.
10+
11+
Currently, the MCP server is available for [Prompt Management](/docs/prompt-management/overview) and will be extended to the rest of the Langfuse data platform in the future. If you have feedback or ideas for new tools, please [share them on GitHub](https://github.com/orgs/langfuse/discussions/10605).
12+
13+
## Configuration
14+
15+
The Langfuse MCP server uses a stateless architecture where each API key is scoped to a specific project. Use the following configuration to connect to the MCP server:
16+
17+
<Tabs items={["Cloud EU", "Cloud US", "HIPAA US", "Self-Hosted"]}>
18+
19+
<Tab>
20+
21+
- Endpoint: `https://cloud.langfuse.com/api/public/mcp`
22+
- Transport: `streamableHttp`
23+
- Authentication: Basic Auth via authorization header
24+
25+
</Tab>
26+
27+
<Tab>
28+
29+
- Endpoint: `https://us.langfuse.com/api/public/mcp`
30+
- Transport: `streamableHttp`
31+
- Authentication: Basic Auth via authorization header
32+
33+
</Tab>
34+
35+
<Tab>
36+
37+
- Endpoint: `https://hipaa.langfuse.com/api/public/mcp`
38+
- Transport: `streamableHttp`
39+
- Authentication: Basic Auth via authorization header
40+
41+
</Tab>
42+
43+
<Tab>
44+
45+
- Endpoint: `https://your-domain.com/api/public/mcp`
46+
- Transport: `streamableHttp`
47+
- Authentication: Basic Auth via authorization header
48+
49+
</Tab>
50+
51+
</Tabs>
52+
53+
## Available Tools
54+
55+
The MCP server provides five tools for comprehensive prompt management.
56+
57+
<Callout type="warning">
58+
**Both read and write tools are available by default.** If you only want to
59+
use read-only tools, configure your MCP client with an allowlist to restrict
60+
access to write operations (`createTextPrompt`, `createChatPrompt`,
61+
`updatePromptLabels`).
62+
</Callout>
63+
64+
### Read Operations
65+
66+
- **`getPrompt`** - Fetch a specific prompt by name with optional label or version
67+
68+
- Supports filtering by production/staging labels
69+
- Returns compiled prompt with metadata
70+
- Read-only operation (auto-approved by clients)
71+
72+
- **`listPrompts`** - List all prompts in the project
73+
- Optional filtering by name, tag, or label
74+
- Cursor-based pagination support
75+
- Returns prompt metadata and available versions
76+
77+
### Write Operations
78+
79+
- **`createTextPrompt`** - Create a new text prompt version
80+
81+
- Supports template variables with `{{variable}}` syntax
82+
- Optional labels, config, tags, and commit message
83+
- Automatic version incrementing
84+
85+
- **`createChatPrompt`** - Create a new chat prompt version
86+
87+
- OpenAI-style message format (role + content)
88+
- Supports system, user, and assistant roles
89+
- Template variables in message content
90+
91+
- **`updatePromptLabels`** - Manage labels across prompt versions
92+
- Add or move labels between versions
93+
- Labels are unique (auto-removed from other versions)
94+
- Cannot modify the auto-managed `latest` label
95+
96+
## Set up
97+
98+
<Steps>
99+
100+
### Get Authentication Header
101+
102+
1. Navigate to your project settings and create or copy a **project-scoped API key**:
103+
- Public Key: `pk-lf-...`
104+
- Secret Key: `sk-lf-...`
105+
2. Encode the credentials to base64 format:
106+
```bash filename="your-base64-token"
107+
echo -n "pk-lf-your-public-key:sk-lf-your-secret-key" | base64
108+
```
109+
110+
### Client Setup
111+
112+
<Tabs items={["Claude Code", "Cursor", "Other MCP Clients"]}>
113+
114+
<Tab>
115+
116+
1. Register the Langfuse MCP server with a single command, replace `{your-base64-token}` with your encoded credentials:
117+
118+
```bash filename="terminal" /{your-base64-token}/
119+
# Langfuse Cloud (EU)
120+
claude mcp add --transport http langfuse https://cloud.langfuse.com/api/public/mcp \
121+
--header "Authorization: Basic {your-base64-token}"
122+
123+
# Langfuse Cloud (US)
124+
claude mcp add --transport http langfuse https://us.langfuse.com/api/public/mcp \
125+
--header "Authorization: Basic {your-base64-token}"
126+
127+
# Self-Hosted (HTTPS required)
128+
claude mcp add --transport http langfuse https://your-domain.com/api/public/mcp \
129+
--header "Authorization: Basic {your-base64-token}"
130+
131+
# Local Development
132+
claude mcp add --transport http langfuse http://localhost:3000/api/public/mcp \
133+
--header "Authorization: Basic {your-base64-token}"
134+
```
135+
136+
2. Verify the connection by asking Claude Code to `list all prompts in the project`. Claude Code should use the `listPrompts` tool to return the list of prompts.
137+
138+
</Tab>
139+
140+
<Tab>
141+
142+
1. Open Cursor Settings (`Cmd/Ctrl + Shift + J`)
143+
2. Navigate to **Tools & Integrations** tab
144+
3. Click **"Add Custom MCP"**
145+
4. Add your Langfuse MCP server configuration, replace `{your-base64-token}` with your encoded credentials:
146+
147+
<Tabs items={["Cloud EU", "Cloud US", "HIPAA US", "Self-Hosted"]}>
148+
149+
<Tab>
150+
151+
```json filename="mcp.json" /{your-base64-token}/
152+
{
153+
"mcp": {
154+
"servers": {
155+
"langfuse": {
156+
"url": "https://cloud.langfuse.com/api/public/mcp",
157+
"headers": {
158+
"Authorization": "Basic {your-base64-token}"
159+
}
160+
}
161+
}
162+
}
163+
}
164+
```
165+
166+
</Tab>
167+
<Tab>
168+
169+
```json filename="mcp.json" /{your-base64-token}/
170+
{
171+
"mcp": {
172+
"servers": {
173+
"langfuse": {
174+
"url": "https://us.cloud.langfuse.com/api/public/mcp",
175+
"headers": {
176+
"Authorization": "Basic {your-base64-token}"
177+
}
178+
}
179+
}
180+
}
181+
}
182+
```
183+
184+
</Tab>
185+
<Tab>
186+
187+
```json filename="mcp.json" /{your-base64-token}/
188+
{
189+
"mcp": {
190+
"servers": {
191+
"langfuse": {
192+
"url": "https://hipaa.cloud.langfuse.com/api/public/mcp",
193+
"headers": {
194+
"Authorization": "Basic {your-base64-token}"
195+
}
196+
}
197+
}
198+
}
199+
}
200+
```
201+
202+
</Tab>
203+
<Tab>
204+
205+
```json filename="mcp.json" /{your-base64-token}/
206+
{
207+
"mcp": {
208+
"servers": {
209+
"langfuse": {
210+
"url": "https://your-domain.com/api/public/mcp",
211+
"headers": {
212+
"Authorization": "Basic {your-base64-token}"
213+
}
214+
}
215+
}
216+
}
217+
}
218+
```
219+
220+
</Tab>
221+
</Tabs>
222+
223+
5. Save the file and restart Cursor
224+
6. The server should appear in the MCP settings with a green dot indicating it's active
225+
226+
</Tab>
227+
228+
<Tab>
229+
230+
- Endpoint: `/api/public/mcp`
231+
- EU: `https://cloud.langfuse.com/api/public/mcp`
232+
- US: `https://us.langfuse.com/api/public/mcp`
233+
- HIPAA: `https://hipaa.langfuse.com/api/public/mcp`
234+
- Self-Hosted: `https://your-domain.com/api/public/mcp`
235+
- Transport: `streamableHttp`
236+
- Authentication: Basic Auth via authorization header
237+
- `Authorization: Basic {your-base64-token}`
238+
239+
</Tab>
240+
</Tabs>
241+
242+
</Steps>
243+
244+
## Use Cases
245+
246+
The MCP server enables powerful workflows for AI-assisted prompt management:
247+
248+
- **Prompt Creation**: "Create a new chat prompt for customer support with system instructions and example messages"
249+
- **Version Management**: "Update the staging label to point to version 3 of the email-generation prompt"
250+
- **Prompt Discovery**: "List all prompts tagged with 'production' and show their latest versions"
251+
- **Iterative Development**: "Create a new version of the code-review prompt with improved instructions"
252+
253+
## Feedback
254+
255+
We'd love to hear about your experience with the Langfuse MCP server. Share your feedback, ideas, and use cases in our [GitHub Discussion](https://github.com/orgs/langfuse/discussions/10605).
256+
257+
## Related Documentation
258+
259+
- [Prompt Management with MCP](/docs/prompt-management/features/mcp-server) - Prompt-specific workflows and examples
260+
- [Prompt Management Overview](/docs/prompt-management/overview) - Learn about Langfuse prompt management
261+
- [Public API](/docs/api-and-data-platform/features/public-api) - REST API for programmatic access

‎pages/docs/api-and-data-platform/overview.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,9 +31,16 @@ import {
3131
Download,
3232
Cloud,
3333
Sliders,
34+
Blocks,
3435
} from "lucide-react";
3536

3637
<Cards num={3}>
38+
<Card
39+
title="MCP Server"
40+
href="/docs/api-and-data-platform/features/mcp-server"
41+
icon={<Blocks />}
42+
arrow
43+
/>
3744
<Card
3845
title="Public API"
3946
href="/docs/api-and-data-platform/features/public-api"

0 commit comments

Comments
 (0)