> ## Documentation Index
> Fetch the complete documentation index at: https://help.gowindmill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Connect Claude Web, Claude Desktop, Claude Code, Codex, Cursor, and other AI tools to Windmill through the MCP server to query team data and run actions from your AI assistant.

Windmill's MCP server lets you interact with Windmill directly from AI tools like Claude Web, Claude Desktop, Claude Code, and Codex. Ask questions about your team, manage 1:1 agendas, check pulse results, look up feedback, and more — all from within your AI assistant.

```
https://mcp.gowindmill.com/mcp
```

> [!NOTE]
>
> MCP access uses your individual Windmill account. Every action exposed through MCP respects your Windmill permissions, but MCP doesn't expose every action available in the Windmill Dashboard.

Each person connects individually in their own AI tool — follow the steps below for your tool of choice.

## Connect with Claude Web or Desktop

Use Windmill's official Claude connector for one-click installation:

[Add Windmill to Claude](https://claude.ai/directory/windmill-hr)

Follow the prompts in Claude to add the connector, then sign in with your Windmill account. The connector will be available in both Claude Web and Claude Desktop.

## Connect with Claude Code

Run this command in your terminal:

```bash theme={null}
claude mcp add --transport http windmill https://mcp.gowindmill.com/mcp
```

Or add this to your MCP configuration file:

```json theme={null}
{
  "windmill": {
    "type": "http",
    "url": "https://mcp.gowindmill.com/mcp"
  }
}
```

Then run `/mcp` in a Claude Code session, select `windmill`, and authenticate.

## Connect with Codex

Run these commands in your terminal:

```bash theme={null}
codex mcp add windmill --url https://mcp.gowindmill.com/mcp
```

Then authenticate:

```bash theme={null}
codex mcp login windmill
```

## Connect with Cursor

Add Windmill to your global Cursor MCP configuration at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "windmill": {
      "url": "https://mcp.gowindmill.com/mcp"
    }
  }
}
```

Save the file, then complete the Windmill OAuth sign-in when Cursor prompts you.

## What you can do

Once connected, you can ask your AI assistant questions and give it instructions that use your Windmill data.

| Area | Read | Change | Limits |
| - | - | - | - |
| Employees and org chart | Employees, reporting lines, groups, counts, and profile information | Update supported employee information | — |
| 1:1s | Series, upcoming events, agendas, and notes | Create 1:1s; update agendas and notes; confirm or remove events; remove series | — |
| Pulse surveys | Pulses, schedules, participants, runs, and responses | Create, test, update, and send Pulses; manage owners; save responses; send Pulse nudges | — |
| Performance reviews | Cycles, participants, reviews, todos, cycle-admin progress, manager-review context, review questions and answers, and draft history | Save drafts and submit your self, peer, upward, and manager reviews | Releasing reviews to employees, peer nominations, and performance-review nudges aren't available through the public MCP |
| Feedback and shoutouts | Feedback, visibility settings, shoutout settings, and available feedback requests | Create, edit, or delete your feedback; give shoutouts; create or cancel eligible feedback requests | Only the requester can cancel a request, and only before it's answered or declined. |
| Workspace members | Members and member counts | Invite members | Removing members isn't available through the public MCP |
| Private notes | Your private notes | Create, update, or delete your private notes | You can access only your own private notes |
| Stats and collaborators | Available stats, employee activity, data counts, and top collaborators | None | — |

See [Ask Windy about results](https://help.gowindmill.com/features/pulse-surveys/ask-windy-about-results.md) and [Responses, runs, and exports](https://help.gowindmill.com/features/pulse-surveys/responses-runs-and-exports.md) for more on analyzing and exporting Pulse results.

### Feedback actions

MCP can create scheduled feedback requests and find incoming or outgoing requests. You can request feedback about yourself or a person in your reporting line. You can cancel a request you created until it's answered or declined.

Company settings control the audiences available when you create feedback. The request tools use the default audience. The edit and delete tools follow your company's [edit window](https://help.gowindmill.com/features/feedback/visibility-and-settings.md#configure-feedback-settings). Feedback linked to a delivered Shoutout cannot be edited or deleted.

See [Feedback](https://help.gowindmill.com/features/feedback.md) for the audience and request rules.

### Performance review actions

MCP can save draft answers and submit reviews that you write: self reviews, peer reviews, upward reviews, and manager reviews. Your AI tool loads the review questions and current answers before it writes. Windmill tells your AI tool to ask you before it submits a review.

You can write only the reviews that you can write in the Windmill Dashboard. MCP can't change a review when its cycle is no longer active. Some review stages must be completed in the Windmill Dashboard. If MCP can't save a review for this reason, it gives you a link to the review in Windmill.

A submitted manager review isn't visible to the employee until the review is released. See [Performance reviews](https://help.gowindmill.com/features/performance-reviews.md) for the review process.

## Authentication and permissions

Windmill's MCP server uses OAuth for authentication. The first time your AI tool calls a Windmill tool, you'll be redirected to your browser to log in with your Windmill account.

Once authenticated, every action exposed through MCP runs through your Windmill account and respects its permissions. If you can't see data in the Windmill Dashboard, you can't access it through MCP. Having access to a Dashboard action doesn't mean MCP exposes an equivalent action.

MCP acts as the signed-in user. Windmill role-based access, org-chart scoping, connected-source permissions, and feature-specific privacy rules all apply. For example, if an Engineering manager asks an AI tool for People Team performance review results they can't see in the Windmill Dashboard, the MCP server will not return that unauthorized data. Performance review visibility remains limited to the management chain and cycle admins.

Data returned by Windmill passes through the connected AI tool's model so the tool can generate an answer. Use AI tools that meet your company's privacy and security requirements.

Once you authorize the MCP server, the connection stays authenticated indefinitely — your AI tool refreshes its credentials silently in the background. There's no scheduled re-authentication, unlike the Windmill Dashboard's seven-day login window. You'll only need to re-authenticate if you remove the MCP server, an admin revokes the connector, or your session is invalidated.

## Advanced: use the Windmill plugin

> [accordion] Connect with the Windmill plugin instead
>
> On paid Claude plans, the Windmill plugin bundles the MCP connection with additional skills for managing 1:1s, creating pulses, and collecting feedback. Most users don't need the plugin — the standard MCP connection above is enough.
>
> **Claude Desktop**
>
> [Connecting Windmill to Claude Desktop with the plugin](https://www.loom.com/embed/545389d0b186412f9bceecfb0ee66e16)
>
> 1. In Claude or Claude Desktop, go to **Customize** → **Plugins**.
> 2. Under **Personal plugins**, click **+** → **Add marketplace**, then add `windmill-dev/windmill-plugin` from a repository.
> 3. Find the Windmill plugin under **Personal**, click it, and click **Install**.
> 4. Click **Manage** → **Connectors** → **Connect** and authenticate in your browser.
>
> **Claude Code**
>
> [Connecting Windmill to Claude Code with the plugin](https://www.loom.com/embed/b4e7b70f04b246b08f78f2afea8e84df)
>
> 1. In a Claude Code session, run `/plugin marketplace add windmill-dev/windmill-plugin`.
> 2. Run `/plugin`, tab to **Marketplaces**, select **Windmill**, install the plugin, then run `/reload-plugins`.
> 3. Run `/mcp`, select `plugin:windmill:windmill`, and authenticate.

## FAQs

> [accordion] Does my whole team need to set this up?
>
> Each person adds the connector and authenticates with their own Windmill account.

> [accordion] What permissions does the MCP server have?
>
> Every action exposed through MCP uses your Windmill account and respects its permissions. Role-based access, org-chart scoping, connected-source permissions, and feature-specific privacy rules all apply. MCP doesn't expose every action available in the Windmill Dashboard.

> [accordion] Is my data sent to the AI model?
>
> When you ask a question, your AI tool calls Windmill's MCP server to fetch the relevant data, then uses that data to answer your question. The data passes through your AI tool's model to generate a response. Windmill's MCP server itself does not send data to any AI model — it only responds to requests from your connected tool.

> [accordion] Can I use MCP with other AI tools?
>
> Windmill's MCP server uses Streamable HTTP with OAuth authentication. Any compatible AI tool can connect using the URL `https://mcp.gowindmill.com/mcp`. The setup steps above cover Claude Web and Desktop, Claude Code, Codex, and Cursor.

> [accordion] How do I disconnect?
>
> Remove the Windmill MCP server from your AI tool's configuration. In Claude Code, run `claude mcp remove windmill`. In Claude Web or Desktop, remove the connector from your settings.

> [accordion] How often do I have to re-authenticate?
>
> There's no time-based expiry on an MCP connection. The OAuth refresh token rotates automatically in the background, so your AI tool stays connected indefinitely. You'll only need to re-authenticate if you remove and re-add the server, revoke the connector, or are signed out by an admin. This differs from the Windmill Dashboard, where login sessions expire after about seven days.

> [accordion] I'm getting authentication errors
>
> Try removing and re-adding the MCP server, then authenticate again. Make sure you're logging in with the same account you use to access the Windmill Dashboard.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.