Skip to content

Commit 9957ec4

Browse files
bogdankosticbogdankostic
authored
docs: Add MCP tool for Haystack documentation (#11349)
1 parent 3b82648 commit 9957ec4

7 files changed

Lines changed: 269 additions & 0 deletions

File tree

‎docs-website/api/mcp.ts‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
// Files under `api/` become HTTP endpoints automatically — this is `/api/mcp`.
2+
import { VercelRequest, VercelResponse } from "@vercel/node";
3+
4+
export default async function handler(req: VercelRequest, res: VercelResponse) {
5+
res.setHeader("Access-Control-Allow-Origin", "*");
6+
res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
7+
res.setHeader(
8+
"Access-Control-Allow-Headers",
9+
"Content-Type, Accept, Mcp-Session-Id, Mcp-Protocol-Version"
10+
);
11+
res.setHeader("Access-Control-Expose-Headers", "Mcp-Session-Id");
12+
13+
if (req.method === "OPTIONS") {
14+
return res.status(204).end();
15+
}
16+
17+
if (req.method !== "POST") {
18+
res.setHeader("Allow", "POST, OPTIONS");
19+
return res.status(405).end("Method Not Allowed");
20+
}
21+
22+
// Get environment variables
23+
const { MCP_WORKSPACE_ID, SEARCH_API_TOKEN } = process.env;
24+
25+
if (!MCP_WORKSPACE_ID || !SEARCH_API_TOKEN) {
26+
return res.status(500).json({ error: "MCP service is not configured." });
27+
}
28+
29+
try {
30+
// Forward the JSON-RPC body unchanged with the API key injected, so we
31+
// don't need to know any MCP methods — new upstream tools just work.
32+
const apiResponse = await fetch(
33+
`https://api.cloud.deepset.ai/api/v2/workspaces/${MCP_WORKSPACE_ID}/mcp`,
34+
{
35+
method: "POST",
36+
headers: {
37+
"Content-Type": "application/json",
38+
Accept:
39+
(req.headers.accept as string) ||
40+
"application/json, text/event-stream",
41+
"X-Client-Source": "haystack-docs",
42+
Authorization: `Bearer ${SEARCH_API_TOKEN}`,
43+
// Forward MCP session id so upstream can correlate requests.
44+
...(req.headers["mcp-session-id"] && {
45+
"Mcp-Session-Id": req.headers["mcp-session-id"] as string,
46+
}),
47+
// Forward the protocol version the client negotiated.
48+
...(req.headers["mcp-protocol-version"] && {
49+
"Mcp-Protocol-Version": req.headers[
50+
"mcp-protocol-version"
51+
] as string,
52+
}),
53+
},
54+
body: JSON.stringify(req.body),
55+
}
56+
);
57+
58+
// Pass the response through as-is (status, content-type, raw body).
59+
const text = await apiResponse.text();
60+
res.status(apiResponse.status);
61+
const contentType = apiResponse.headers.get("content-type");
62+
if (contentType) res.setHeader("Content-Type", contentType);
63+
// Surface the session id back to the client (browsers can read it because
64+
// it's in Access-Control-Expose-Headers above).
65+
const sessionId = apiResponse.headers.get("mcp-session-id");
66+
if (sessionId) res.setHeader("Mcp-Session-Id", sessionId);
67+
return res.send(text);
68+
} catch (error) {
69+
console.error("MCP proxy error:", error);
70+
return res.status(502).json({ error: "Failed to reach MCP upstream." });
71+
}
72+
}

‎docs-website/api/well-known.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
// Returns a JSON 404 for OAuth discovery probes (e.g.
2+
// `/.well-known/oauth-protected-resource`, `/.well-known/oauth-authorization-server`).
3+
// Per RFC 9728 / the MCP authorization spec a 404 here means "this resource
4+
// doesn't require OAuth — connect anonymously." Without this handler the
5+
// Docusaurus catch-all serves an HTML 404, which trips MCP clients that try to
6+
// JSON-parse the body to extract an OAuth error.
7+
import { VercelRequest, VercelResponse } from "@vercel/node";
8+
9+
export default function handler(_req: VercelRequest, res: VercelResponse) {
10+
res.setHeader("Content-Type", "application/json");
11+
res.setHeader("Cache-Control", "public, max-age=3600");
12+
return res.status(404).end("{}");
13+
}

‎docs-website/docs/overview/docs-mcp-server.mdx‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
title: "Using Haystack Docs in Your Coding Agent"
3+
id: docs-mcp-server
4+
slug: "/docs-mcp-server"
5+
description: "Connect your coding agent to the Haystack documentation through the public MCP server. Includes setup instructions for Claude Code, Cursor, and GitHub Copilot."
6+
---
7+
8+
import Tabs from '@theme/Tabs';
9+
import TabItem from '@theme/TabItem';
10+
11+
# Using Haystack Docs in Your Coding Agent
12+
13+
Haystack publishes a public [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that lets coding agents search the official Haystack documentation. Pointing your agent at it means it answers questions from up-to-date docs instead of relying on training data, which can lag behind the framework.
14+
15+
The server exposes a single tool, `search_haystack_docs`, that returns relevant documentation sections with source URLs. No API key or sign-up is needed.
16+
17+
## Server URL
18+
19+
```
20+
https://docs.haystack.deepset.ai/api/mcp
21+
```
22+
23+
The server speaks **HTTP** transport. Most agents auto-detect this. If yours asks you to choose, pick `http`.
24+
25+
## Setup
26+
27+
<Tabs>
28+
<TabItem value="claude-code" label="Claude Code" default>
29+
30+
Add the server with the `claude mcp` CLI:
31+
32+
```shell
33+
claude mcp add --transport http haystack-docs https://docs.haystack.deepset.ai/api/mcp
34+
```
35+
36+
Restart your Claude Code session. Verify it's connected by running `/mcp` — you should see `haystack-docs` listed with the `search_haystack_docs` tool.
37+
38+
For more options (project vs. user scope, SSE transport, headers), see the [Claude Code MCP docs](https://code.claude.com/docs/en/mcp).
39+
40+
</TabItem>
41+
<TabItem value="cursor" label="Cursor">
42+
43+
Open Cursor settings → **Tools & MCPs** → **Add new MCP server**, or edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project) directly:
44+
45+
```json
46+
{
47+
"mcpServers": {
48+
"haystack-docs": {
49+
"url": "https://docs.haystack.deepset.ai/api/mcp"
50+
}
51+
}
52+
}
53+
```
54+
55+
Save the file and reload Cursor. The tool appears in the **Available Tools** list inside the chat panel.
56+
57+
See the [Cursor MCP docs](https://cursor.com/docs/context/mcp) for the full configuration reference.
58+
59+
</TabItem>
60+
<TabItem value="copilot" label="GitHub Copilot">
61+
62+
In VS Code, create or edit `.vscode/mcp.json` in your workspace:
63+
64+
```json
65+
{
66+
"servers": {
67+
"haystack-docs": {
68+
"type": "http",
69+
"url": "https://docs.haystack.deepset.ai/api/mcp"
70+
}
71+
}
72+
}
73+
```
74+
75+
Open the Copilot Chat panel, switch to **Agent** mode, then click the tools icon and enable `haystack-docs`. You can also register the server globally from the command palette via **MCP: Add Server**.
76+
77+
See [Add and manage MCP servers in VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for the full configuration reference.
78+
79+
</TabItem>
80+
</Tabs>
81+
82+
## Verifying it works
83+
84+
Ask your agent a question that requires current Haystack knowledge, for example:
85+
86+
> What are the required methods on a Haystack custom component?
87+
88+
The agent should call `search_haystack_docs` and cite source URLs under `docs.haystack.deepset.ai` in its answer. If it answers without calling the tool, prompt it explicitly: *"Use the haystack-docs MCP server to answer."*

‎docs-website/sidebars.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ export default {
1515
items: [
1616
'overview/installation',
1717
'overview/get-started',
18+
'overview/docs-mcp-server',
1819
'overview/faq',
1920
'overview/telemetry',
2021
'overview/breaking-change-policy',

‎docs-website/vercel.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,10 @@
11
{
2+
"rewrites": [
3+
{
4+
"source": "/.well-known/:path*",
5+
"destination": "/api/well-known"
6+
}
7+
],
28
"redirects": [
39
{
410
"source": "/docs/2.21/:slug*",

‎docs-website/versioned_docs/version-2.29/overview/docs-mcp-server.mdx‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
title: "Using Haystack Docs in Your Coding Agent"
3+
id: docs-mcp-server
4+
slug: "/docs-mcp-server"
5+
description: "Connect your coding agent to the Haystack documentation through the public MCP server. Includes setup instructions for Claude Code, Cursor, and GitHub Copilot."
6+
---
7+
8+
import Tabs from '@theme/Tabs';
9+
import TabItem from '@theme/TabItem';
10+
11+
# Using Haystack Docs in Your Coding Agent
12+
13+
Haystack publishes a public [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that lets coding agents search the official Haystack documentation. Pointing your agent at it means it answers questions from up-to-date docs instead of relying on training data, which can lag behind the framework.
14+
15+
The server exposes a single tool, `search_haystack_docs`, that returns relevant documentation sections with source URLs. No API key or sign-up is needed.
16+
17+
## Server URL
18+
19+
```
20+
https://docs.haystack.deepset.ai/api/mcp
21+
```
22+
23+
The server speaks **HTTP** transport. Most agents auto-detect this. If yours asks you to choose, pick `http`.
24+
25+
## Setup
26+
27+
<Tabs>
28+
<TabItem value="claude-code" label="Claude Code" default>
29+
30+
Add the server with the `claude mcp` CLI:
31+
32+
```shell
33+
claude mcp add --transport http haystack-docs https://docs.haystack.deepset.ai/api/mcp
34+
```
35+
36+
Restart your Claude Code session. Verify it's connected by running `/mcp` — you should see `haystack-docs` listed with the `search_haystack_docs` tool.
37+
38+
For more options (project vs. user scope, SSE transport, headers), see the [Claude Code MCP docs](https://code.claude.com/docs/en/mcp).
39+
40+
</TabItem>
41+
<TabItem value="cursor" label="Cursor">
42+
43+
Open Cursor settings → **Tools & MCPs** → **Add new MCP server**, or edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project) directly:
44+
45+
```json
46+
{
47+
"mcpServers": {
48+
"haystack-docs": {
49+
"url": "https://docs.haystack.deepset.ai/api/mcp"
50+
}
51+
}
52+
}
53+
```
54+
55+
Save the file and reload Cursor. The tool appears in the **Available Tools** list inside the chat panel.
56+
57+
See the [Cursor MCP docs](https://cursor.com/docs/context/mcp) for the full configuration reference.
58+
59+
</TabItem>
60+
<TabItem value="copilot" label="GitHub Copilot">
61+
62+
In VS Code, create or edit `.vscode/mcp.json` in your workspace:
63+
64+
```json
65+
{
66+
"servers": {
67+
"haystack-docs": {
68+
"type": "http",
69+
"url": "https://docs.haystack.deepset.ai/api/mcp"
70+
}
71+
}
72+
}
73+
```
74+
75+
Open the Copilot Chat panel, switch to **Agent** mode, then click the tools icon and enable `haystack-docs`. You can also register the server globally from the command palette via **MCP: Add Server**.
76+
77+
See [Add and manage MCP servers in VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for the full configuration reference.
78+
79+
</TabItem>
80+
</Tabs>
81+
82+
## Verifying it works
83+
84+
Ask your agent a question that requires current Haystack knowledge, for example:
85+
86+
> What are the required methods on a Haystack custom component?
87+
88+
The agent should call `search_haystack_docs` and cite source URLs under `docs.haystack.deepset.ai` in its answer. If it answers without calling the tool, prompt it explicitly: *"Use the haystack-docs MCP server to answer."*

‎docs-website/versioned_sidebars/version-2.29-sidebars.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
"items": [
1212
"overview/installation",
1313
"overview/get-started",
14+
"overview/docs-mcp-server",
1415
"overview/faq",
1516
"overview/telemetry",
1617
"overview/breaking-change-policy",

0 commit comments

Comments
 (0)