> ## 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 Code, Claude Desktop, Codex, Cursor, and other AI tools to Windmill through the MCP server to query team data and run actions from your IDE.

Windmill's MCP server lets you interact with Windmill directly from AI coding tools like Claude Code, Claude Desktop, 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. You'll authenticate with your own credentials, and all actions respect the same permissions you have in the Windmill Dashboard.
</Note>

Each person connects individually in their own AI tool — follow the steps below for your tool of choice. Admins on Claude **Team** or **Enterprise** plans can optionally [pre-enable the Windmill connector for everyone](#for-admins-enable-for-your-whole-org-optional) so members can connect with one click.

## Connect with Claude Desktop

If your admin has [pre-enabled Windmill for your organization](#for-admins-enable-for-your-whole-org-optional), open Claude Desktop, go to **Settings** → **Connectors**, and click **Connect** next to Windmill. Your browser opens to complete sign-in with your Windmill account.

Otherwise, add Windmill as a custom connector:

<Steps>
  <Step title="Open custom connector settings">
    In Claude Desktop, go to **Settings** → **Connectors** and click **Add custom connector**.
  </Step>

  <Step title="Enter details">
    Fill in the following and save:

    * **Name:** `Windmill`
    * **URL:** `https://mcp.gowindmill.com/mcp`
    * Leave **OAuth Client ID** and **OAuth Client Secret** empty
  </Step>

  <Step title="Connect">
    Click **Connect** next to Windmill. Your browser opens to complete sign-in.
  </Step>
</Steps>

## 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
```

## What you can do

Once connected, you can ask your AI assistant questions and give it instructions that use your Windmill data. Here are some examples across Windmill's features.

### Employees and org chart

* "Who reports to Sarah Chen?"
* "How many people are on the engineering team?"
* "Show me everyone in the Sales group"
* "What's Jordan's job title and start date?"

### 1:1s

* "What 1:1s do I have coming up this week?"
* "Add 'discuss Q2 goals' to my 1:1 agenda with Alex"
* "Show me my 1:1 notes from last week with Jamie"
* "Create a new 1:1 with Sam Rivera"

### Pulse surveys

* "Show me the latest responses to our engagement pulse"
* "Create a pulse asking the engineering team about workload"
* "How many people have responded to the onboarding pulse?"
* "Send a reminder nudge for the open pulse"
* "Using our latest onsite Pulse, what are the top 3 things we should improve and what are 2–3 concrete ideas we could implement?"

Claude reads Pulse responses (and the post-pulse report) through the MCP server and synthesizes the result. MCP only exposes data you can already see in the Windmill Dashboard — if you can't see the Pulse in Windmill, Claude can't access it via MCP either. See [Pulse Surveys](/features/pulse-surveys/index) for more on filtering and exporting Pulse results.

### Performance reviews

* "What review cycles are currently running?"
* "Who's participating in the Q1 review cycle?"
* "Show me the reviews written for Taylor last cycle"
* "What stage is the current review cycle in?"
* "What do I need to do for my current review cycle?"

### Feedback

* "Give feedback to Morgan: they did a great job leading the sprint retro"
* "Request feedback from Dana about my presentation"
* "Show me the feedback I've received this quarter"
* "Give a shoutout to the design team for the rebrand launch"

### Recaps

* "Show me the weekly recap for Chris from last week"
* "What has the product team been up to recently?"

### Stats and activity

* "Show me a breakdown of Riley's activity across tools"
* "What are the available stat types?"
* "Who are my top collaborators this quarter?"

### Workspace management

* "How many members are in the workspace?"
* "Invite [jane@company.com](mailto:jane@company.com) to the workspace"

### Private notes

* "Create a note about my conversation with Pat today"
* "Show me my notes on Alex"

## 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, all actions go through your account with the same permissions you have in the Windmill Dashboard. If you can't see something in the Windmill Dashboard, you can't access it via MCP either.

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.

## For admins: enable for your whole org (optional)

If you're on a Claude **Team** or **Enterprise** plan, an Owner or Primary Owner can pre-enable the Windmill connector for the organization. This makes it available to everyone under **Settings** → **Connectors** in Claude Desktop with one-click authentication — members don't have to add it as a custom connector themselves. Each person still authenticates individually with their own Windmill account.

This step is optional. Individuals can always add Windmill as a custom connector on their own using the [Claude Desktop steps above](#connect-with-claude-desktop).

<Steps>
  <Step title="Open organization connector settings">
    Go to [claude.ai/admin-settings/connectors](https://claude.ai/admin-settings/connectors).
  </Step>

  <Step title="Add a custom web connector">
    Click **Add** → **Custom** → **Web**.
  </Step>

  <Step title="Enter details">
    Fill in the following and save:

    * **Name:** `Windmill`
    * **URL:** `https://mcp.gowindmill.com/mcp`
    * Leave **OAuth Client ID** and **OAuth Client Secret** empty
  </Step>
</Steps>

## Advanced: use the Windmill plugin

<Accordion title="Connect with the Windmill plugin instead">
  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**

  <iframe src="https://www.loom.com/embed/545389d0b186412f9bceecfb0ee66e16" title="Connecting Windmill to Claude Desktop with the plugin" frameborder="0" className="w-full aspect-video rounded-xl" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

  1. Navigate to the **Cowork** or **Code** tab.
  2. Go to **Personal plugins** → **Create plugin** → **Add marketplace** and enter `windmill-dev/windmill-plugin`.
  3. Find the Windmill plugin under **Personal**, click it, and click **Install**.
  4. Click **Manage** → **Connectors** → **Connect** and authenticate in your browser.

  **Claude Code**

  <iframe src="https://www.loom.com/embed/b4e7b70f04b246b08f78f2afea8e84df" title="Connecting Windmill to Claude Code with the plugin" frameborder="0" className="w-full aspect-video rounded-xl" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

  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.
</Accordion>

## FAQs

<AccordionGroup>
  <Accordion title="Does my whole team need to set this up?">
    Each person authenticates individually in their own AI tool. There's no required admin setup. Optionally, on Claude **Team** and **Enterprise** plans, an Owner or Primary Owner can [pre-enable the Windmill connector](#for-admins-enable-for-your-whole-org-optional) at [claude.ai/admin-settings/connectors](https://claude.ai/admin-settings/connectors) so members can connect with one click instead of adding a custom connector themselves.
  </Accordion>

  <Accordion title="What permissions does the MCP server have?">
    The MCP server acts as you. It has the same read and write access you have in the Windmill Dashboard. Role-based access, org-chart scoping, connected-source permissions, and feature-specific privacy rules all apply. If you can't see something in the Windmill Dashboard, you can't access it via MCP.
  </Accordion>

  <Accordion title="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>

  <Accordion title="Can I use MCP with other AI tools?">
    Windmill's MCP server uses the open MCP standard over HTTP with OAuth authentication. Any AI tool that supports MCP over HTTP can connect using the URL `https://mcp.gowindmill.com/mcp`. This includes tools like Cursor, Notion, and Poke.
  </Accordion>

  <Accordion title="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 Desktop, remove the connector from your Customization settings.
  </Accordion>

  <Accordion title="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>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>