--- title: MCP server url: /docs/ai/guides/set-up-mcp-server/ --- The Pulumi [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server gives the AI agent you already use access to Pulumi. Through it, an agent can list your stacks, search your resources, check policy violations, look up resource schemas in the Pulumi Registry, and hand tasks to [Pulumi Neo](/docs/ai/concepts/neo/). For background on MCP in infrastructure work, see [MCP for infrastructure as code](/what-is/mcp-for-infrastructure-as-code/). Pulumi hosts the server at `https://mcp.ai.pulumi.com/mcp`, so there is nothing to install or run locally. > [!INFO] > This page is about connecting your own AI agent to Pulumi. For the opposite direction, connecting Neo to other services' MCP servers (Jira, Datadog, and others), see [External MCP servers](/docs/ai/integrations/external-mcp-servers/). ## Configuration Add the server to your agent, then authenticate with a Pulumi access token the first time the agent connects. See [Authentication](#authentication) for what the token is used for and how to choose an organization. ### Claude Code ```bash claude mcp add --transport http pulumi https://mcp.ai.pulumi.com/mcp ``` Then run `/mcp` in Claude Code, select **pulumi**, and authenticate in the browser window that opens. ### Cursor [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=pulumi&config=eyJ0cmFuc3BvcnQiOiJodHRwIiwidXJsIjoiaHR0cHM6Ly9tY3AuYWkucHVsdW1pLmNvbS9tY3AifQ%3D%3D) Or add the server to `.cursor/mcp.json` in your home directory or project root: ```json { "mcpServers": { "pulumi": { "url": "https://mcp.ai.pulumi.com/mcp" } } } ``` Then select **Connect** next to the server under **Cursor Settings > Tools & MCP** and authenticate in the browser. ### Claude Desktop 1. Open **Settings > Connectors** and select **Add custom connector**. 1. Set the name to `Pulumi` and the URL to `https://mcp.ai.pulumi.com/mcp`. 1. Restart Claude Desktop and authenticate in the browser when prompted. ### Windsurf Add the server to Windsurf's MCP configuration (**Windsurf Settings > MCP Servers**), then authenticate in the browser when prompted: ```json { "mcpServers": { "pulumi": { "serverUrl": "https://mcp.ai.pulumi.com/mcp" } } } ``` ### Kiro Kiro connects to remote MCP servers through the [mcp-remote](https://www.npmjs.com/package/mcp-remote) package, which requires Node.js. Add the server to Kiro's [`mcp.json`](https://kiro.dev/docs/mcp/configuration/#configuration-locations), then authenticate in the browser when prompted: ```json { "mcpServers": { "pulumi": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.ai.pulumi.com/mcp"] } } } ``` ### Other agents Any agent that supports remote MCP servers over streamable HTTP with OAuth can connect to `https://mcp.ai.pulumi.com/mcp`. Agents that only support local (stdio) servers can use `mcp-remote` as shown for Kiro. ## Authentication The MCP server calls Pulumi Cloud with a Pulumi [access token](/docs/administration/concepts/access-tokens/) that you provide. Every call runs as that token's identity, so the agent can see and do exactly what the token can, under your organization's [RBAC](/docs/administration/concepts/rbac/) settings, and nothing more. See [Choose a token](#choose-a-token) for which kind to use. ### Authenticate in the browser The first time your agent connects, it opens a browser window: 1. Paste a Pulumi access token. 1. Select the organization the server should use by default. 1. Confirm the redirect URL and select **Authorize Connection**. 1. Return to your agent. The server stores the token encrypted and uses it for every call until the session ends. Sessions last 30 days, after which the agent asks you to authenticate again. If you delete the token, or it expires, before then, tool calls fail until you authenticate again with a new token. To switch the default organization, disconnect and reconnect the server in your agent and choose a different organization. You can also name an organization in a request ("list the stacks in the acme org") and the agent passes it to the tool. ### Choose a token The token you give the MCP server is separate from the one the Pulumi CLI uses (stored by `pulumi login` or set in `PULUMI_ACCESS_TOKEN`), so create a separate one for the MCP server. You can then revoke or rotate it without affecting the CLI. The server accepts any Pulumi access token, but two kinds are most useful: - **An [organization token](/docs/administration/concepts/access-tokens/#creating-an-organization-access-token)** acts as the organization with whatever [role](/docs/administration/concepts/rbac/roles/) you assign it, and works in a single organization. This is the way to limit what the agent can see and do in Pulumi Cloud, for example by assigning a role that can only read stacks. Don't rely on the token's role to block [Neo tasks](#costs-and-edition-requirements), though: deny `neo-bridge` in your agent as well if you want the agent to be read-only. Organization tokens are available in Essentials, Pro, Enterprise. - **A [personal access token](/docs/administration/concepts/access-tokens/#personal-access-tokens)** acts as you, with your permissions in every organization you belong to. Create one at [app.pulumi.com/account/tokens](https://app.pulumi.com/account/tokens). If your organization enforces an [access token expiry policy](/docs/administration/concepts/access-tokens/#access-token-expiry-policy), the token must meet it, or calls against that organization fail. ### Authenticate without a browser For CI pipelines and headless agents, skip the browser flow by sending the token in an `Authorization` header. The server validates the token on every request and stores nothing, so there is no session to expire. Add an `X-Pulumi-Org` header to choose the organization: ```json { "mcpServers": { "pulumi": { "url": "https://mcp.ai.pulumi.com/mcp", "headers": { "Authorization": "Bearer ${PULUMI_MCP_TOKEN}", "X-Pulumi-Org": "acme" } } } } ``` Read the token from an environment variable or secret store rather than committing it, and check how your agent expands variables in its MCP configuration. > [!WARNING] > If `X-Pulumi-Org` names an organization the token can't access, or you omit the header, the server uses the first organization the token can access, without returning an error. Check the organization name carefully when using a personal token that belongs to more than one organization. ## Costs and edition requirements Most of the server's tools only read data, and the server itself never runs `pulumi up` or changes your infrastructure. What the tools need from your organization: | Tools | What they need | Cost | |---|---|---| | Registry tools, `deploy-to-aws`, and all prompts | Any Pulumi account | None. They return schemas and instructions that your agent's own model works with. | | `get-stacks`, `get-users`, `get-policy-violations` | Any Pulumi Cloud organization | None | | `resource-search` | [Resource search](/docs/discovery-governance/concepts/discovery/querying-resources/), available in Essentials, Pro, Enterprise | Included in your edition | | `neo-bridge` | [Pulumi Neo](/docs/ai/concepts/neo/), available in Essentials, Pro, Enterprise | Neo usage is billed to your organization | `neo-bridge` is the tool that can cost money. Each task it starts, and each message or approval it sends, runs Neo in Pulumi Cloud, which counts against your organization's Neo usage as it would in the Pulumi Cloud console. Approving a Neo request can also let Neo change infrastructure or open pull requests. Admins can cap that spend with [Neo usage limits](/docs/ai/concepts/neo/usage-limits/); see [pricing](/pricing/) for rates. To keep an agent from starting Neo work, deny `neo-bridge` in your agent's tool permissions. Restricting the token's role isn't enough on its own to prevent Neo tasks. In Claude Code, add `mcp__pulumi__neo-bridge` to `permissions.deny` in `settings.json`; in Cursor, turn the tool off under **Tools & MCP**. ## Tools and prompts The server exposes tools for Pulumi Cloud, Neo, the Pulumi Registry, and code generation, plus reusable prompts for deployment and migration work. You don't call the tools directly: describe what you want and your agent picks the tool. For the full list, see [MCP server tools and prompts](/docs/ai/reference/mcp-server-tools/). ## Example requests - "What stacks do I have, and which ones haven't been updated in the last 90 days?" - "Find every S3 bucket without tags and tell me which stacks they're in." - "Look up the properties for an Azure Container Registry with geo-replication and write the TypeScript for it." - "What policy violations do my production stacks have?" - "Ask Neo to restrict every security group that allows SSH from 0.0.0.0/0 and open a pull request." ## Troubleshooting **The token is rejected.** Check that the token hasn't expired or been deleted at [app.pulumi.com/account/tokens](https://app.pulumi.com/account/tokens), and that it complies with your organization's token expiry policy. **The agent sees the wrong organization.** Reconnect the server and pick the right organization, or name the organization in your request. With header authentication, check the spelling of `X-Pulumi-Org`. **The agent asks you to authenticate again.** Browser sessions last 30 days. Authenticate again to start a new session. **New or renamed tools don't appear.** Some agents, including Cursor, cache tool definitions. Restart the agent or reconnect the server. **A tool reports "Quota limit exceeded" or "Forbidden".** A quota error usually means the feature isn't available in your organization's edition; see [Costs and edition requirements](#costs-and-edition-requirements). "Forbidden" means the token's role lacks permission; see [Choose a token](#choose-a-token). **Neo tasks don't start.** Check that Neo is enabled for your organization and that it hasn't reached its [usage limit](/docs/ai/concepts/neo/usage-limits/). ## Next steps - [Pulumi Agent Skills](/docs/ai/concepts/agent-skills/): teach your agent proven Pulumi workflows. - [Pulumi Neo](/docs/ai/concepts/neo/): Pulumi's infrastructure agent. - [Agent accounts](/docs/administration/concepts/agent-accounts/): Pulumi Cloud accounts that agents provision for themselves. - [Access tokens](/docs/administration/concepts/access-tokens/): personal, organization, and team tokens. - [What is agentic infrastructure?](/what-is/what-is-agentic-infrastructure/)