> For the complete documentation index, see [llms.txt](https://help.usehaystack.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.usehaystack.io/features/mcp-server.md). # MCP Server Connect Haystack Delivery to Claude, Cursor or GitHub Copilot and ask your delivery data questions in plain language. Read-only, and nothing to install. Read-only access to your Haystack data from Claude, Cursor and GitHub Copilot. Nothing to install. The connection inherits your access level. You see exactly what you already see in the web app, and nothing more. {% hint style="info" %} This guide covers **Delivery**, at `delivery.usehaystack.io`. If you sign in at `dora.usehaystack.io`, you are on DORA — the setup guide for that is at [support.usehaystack.io](https://support.usehaystack.io/en/articles/17734366-connecting-the-haystack-mcp-server). {% endhint %} ## What you can ask about Around 40 tools. Whatever your setup, you get: * **Pull requests** — open and merged PRs by team, reviewers, review load, bot activity, and at-risk work with reasons and ages * **Flow metrics** — cycle time, change lead time, throughput and time in status, per team and over any window * **Teams and people** — team structure, membership, unassigned members, new joiners And depending on what your organization uses: * **Sprints and Jira** — sprint goals and status, per-sprint analytics, boards, projects, statuses and member mapping, if Jira is connected * **Surveys** — results and AI summaries, if Surveys is on your plan The difference from a dashboard is the second question. "Why did that go up?" costs you nothing, so you ask it. ## Before you start You need three things. | What | Why | | ------------------------ | ----------------------------------------------------------------------------------------------------- | | **A Haystack account** | The connection inherits your access level. You see exactly what you already see in the web app. | | **A Personal API Token** | Created in your Haystack settings. Step 1 below. | | **An MCP client** | Claude Code, Claude Desktop, Claude on the web, Cursor, or VS Code with GitHub Copilot in agent mode. | ## 1. Create your Personal API Token At **delivery.usehaystack.io** 1. Sign in, then open **Org Settings → API** (`/api-tokens`). 2. Click **+ Create token** and name it after the client, for example `Claude — laptop`. 3. Copy it immediately. The token is shown only once. ![The Delivery Org Settings API page](https://933147321-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbiIqB8vq91hNrILQ1MAF%2Fuploads%2Fq7RddWaPX9sYQgbnefOV%2Fmcp-delivery-api-tokens.png?alt=media) *Org Settings → API. Existing tokens list a revoke action; Create token sits top right.* {% hint style="warning" %} **Treat the token like a password.** Tokens are long-lived, read-only and revocable from the same page. Use one token per client, so revoking one does not break the others. Never commit a token, paste it into a ticket, or share it in chat. If a device or token is exposed, revoke it and create a replacement. {% endhint %} ## 2. One server URL ``` https://mcp.usehaystack.io/mcp ``` Streamable HTTP · OAuth with automatic client registration Every client below connects to that same hosted endpoint. When your client sends you to the Haystack authorization page it asks for one thing: your Personal API Token. Paste it, submit, and you are returned to the client with the tools enabled. ![The Haystack authorization page, asking for a Personal API Token](https://933147321-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbiIqB8vq91hNrILQ1MAF%2Fuploads%2FIY67Sh1exrKTeIQZ0cKd%2Fmcp-authorization-page.png?alt=media) *The authorization page. Paste your token, click Authorize Access, and you are redirected back automatically.* ## 3. Client setup Five clients, one endpoint. Find yours and skip the rest. {% tabs %} {% tab title="Claude Code (CLI)" %} ```bash claude mcp add --transport http -s user haystack https://mcp.usehaystack.io/mcp ``` Start Claude Code, run `/mcp`, select **haystack → Authenticate**, and paste your token in the browser page that opens. The entry then reads `connected`. **Scope** `-s user` covers all your projects on this machine (recommended). `-s local` is this project only. `-s project` shares the entry with your team through `.mcp.json`, and each teammate authenticates with their own token. Manage entries with `claude mcp list` and `claude mcp remove haystack`. [Client reference](https://docs.claude.com/en/docs/claude-code/mcp) {% endtab %} {% tab title="Claude Desktop" %} 1. Open **Settings → Connectors → Add custom connector**. 2. Name it `Haystack` and enter the server URL. 3. Click **Connect** and paste your token on the Haystack page. 4. Enable Haystack from the tools menu in a new chat. Claude's own support site covers custom connectors via remote MCP in more detail. {% endtab %} {% tab title="Claude on the web" %} Same flow as Desktop: **Settings → Connectors → Add custom connector**, enter the URL, connect, paste your token, then enable Haystack from the tools menu in a new chat. {% hint style="info" %} On Team and Enterprise plans an admin may need to approve custom connectors, or add Haystack once for the whole workspace. Each member still authenticates with their own token. {% endhint %} {% endtab %} {% tab title="Cursor" %} Create `~/.cursor/mcp.json` for all projects, or `.cursor/mcp.json` for one: ```json { "mcpServers": { "haystack": { "url": "https://mcp.usehaystack.io/mcp" } } } ``` Open **Cursor Settings → MCP & Integrations**, click **Connect** or **Needs login** on the haystack entry, paste your token, then ask a question in Agent mode. [Client reference](https://cursor.com/docs/context/mcp) {% endtab %} {% tab title="GitHub Copilot in VS Code" %} Create `.vscode/mcp.json` in the workspace, or run **MCP: Add Server…** from the Command Palette and choose HTTP: ```json { "servers": { "haystack": { "type": "http", "url": "https://mcp.usehaystack.io/mcp" } } } ``` Click **Start** above the server entry, paste your token on the Haystack page, then open Copilot Chat in Agent mode and confirm `haystack` is ticked in the tools picker. {% hint style="info" %} Organizations with Copilot policy management may need an admin to allow MCP servers first. {% endhint %} [Client reference](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) {% endtab %} {% endtabs %} ## 4. Check that it works Ask something that forces a tool call: > "Using Haystack, who am I and which organization am I in?" > > "List my Haystack teams." > > "Which pull requests are at risk in the last 30 days?" If the assistant answers without calling a tool, tell it to use the Haystack tools explicitly, and check that the server shows as connected in your client's MCP panel. ## 5. Your first ten minutes Once you are connected, these are the questions worth starting with. They are ordered so each one pays off before the next asks anything of you. **Ask the question you actually came with.** Not a test question — the real one, the thing you would otherwise have exported a spreadsheet for. No question in mind? Start with one of your busier squads: > "What's blocking the \[squad] team right now?" You will get named pull requests, who owns them, how long they have been sitting, and why each one is flagged. **Then ask the follow-up.** This is the part worth learning, and it is easy to miss: > "Why is that one stuck?" > > "Which of those is oldest, and who's reviewing it?" Follow-ups cost you nothing. That is the real difference from a dashboard — not the first answer, the fourth one. **Try a before-and-after.** Pick a change your team made — a process change, a reorganisation, a tooling switch: > "We changed \[the thing] on \[date]. Compare the eight weeks before and the eight weeks after, for \[squad]." **Make it a habit.** The question that brings people back is the retro one. Run it before your next retro or sprint review and you will walk in with the summary already written: > "Summarise the last two sprints for \[squad] — cycle time and time-in-status trends." ## 6. Limitations worth knowing A few things worth knowing before you meet them. * **Per-team sprint filtering matches on the Jira board behind the team.** A team not linked to a board holding sprints correctly returns none, rather than erroring. * **Survey AI summaries are generated on request**, not automatically when a snapshot closes. Ask for one and it is produced in under a minute. * **A query that runs longer than 30 seconds fails.** Narrow the date range or ask for fewer results and retry. ## 7. If something goes wrong | Symptom | Fix | | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | **Connected, but no tools appear — or a 403** | Get in touch and we will take a look, then reconnect the server in your client. | | **401 Unauthorized** | The token was mistyped, revoked, or pasted with a trailing space. Create a fresh one and re-authenticate. | | **Config changes have no effect** | Fully quit and relaunch the client. MCP config is read at startup only. | | **Every client fails at once** | Suspect an outage rather than your setup. Get in touch instead of re-adding the server. | | **"Unable to reach the Haystack API"** | Usually a query that took too long rather than a connection problem. Narrow the date range or ask for fewer results, then retry. | | **An answer looks suspiciously empty** | Ask the assistant which query produced the figure. Some tools only apply to certain team types, and it will tell you which one to use instead. | {% hint style="info" %} **Read-only, by design** Personal API Tokens are restricted server-side to read endpoints, so an assistant cannot change Haystack data. Tokens are held in memory on the MCP server to serve your session, never written to a database or logs. Revoking one in Haystack cuts access at the source; a cached copy can persist on the server for up to an hour. {% endhint %} ## More Protocol reference: [modelcontextprotocol.io](https://modelcontextprotocol.io) Questions, or an answer that looks wrong: your Haystack contact, or [support.usehaystack.io](https://support.usehaystack.io/en/) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://help.usehaystack.io/features/mcp-server.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.