MCP setup
Connect an MCP client by signing in with your Envpilot account. There is no key to create, store in an environment variable, or rotate. The connection acts as you: it sees the projects, variables and documentation your role can see, and nothing more.
https://www.envpilot.dev/api/mcpTransport is Streamable HTTP. The organization needs the Pro plan (mcp_server).
Connect#
Add the server to your client#
Use the URL above and no Authorization header. The exact config for Claude, Claude Code, Codex, Cursor and VS Code is on Connecting a client.
Sign in#
Connect the server. Your browser opens the Envpilot sign-in page. Sign in and approve the client. The client keeps the token and renews it on its own.
Check the tools loaded#
In Claude Code run /mcp; other clients show the server's tools in their MCP panel. A signed-in connection lists nineteen tools.
What a connection can see#
- Your role decides. The connection reads exactly what you can read in the dashboard: the same projects, environments, variable permissions and documentation. A suspended membership sees nothing.
- Nineteen tools for projects, variables, secret files, shared accounts, change requests and documentation. See Tools.
- Writes follow your role. An agent can create and update what you can in the dashboard. A protected environment turns a write into a change request, and documentation stays a draft until a person publishes it. Clients that honour
destructiveHint, such as Claude, ask you before each write. - More than one organization: pass
organization(the organization's slug) to the project tools;envpilot_list_organizationslists them.envpilot_get_docandenvpilot_update_doc_drafttake a doc id, which already names the project. The error message lists the slugs you can use. - Audited and rate limited per person. Every value read is logged against your user.
How sign-in works#
- The client calls the server without a token and gets
401with a link to the server's metadata. - The metadata names Envpilot's sign-in service. The client registers itself there and opens the sign-in page in your browser.
- After you approve, the client receives an access token issued for this server only.
- Every call is checked twice: the server verifies the token's signature, issuer, audience and expiry, and Envpilot's backend verifies it again before reading anything. The token cannot be used against the dashboard.
Moving from an API key#
- Remove the key from the client's config: the
Authorizationheader in Claude Code or Cursor, orbearer_token_env_varin Codex. A client that still sends a header never offers sign-in. - Reconnect and sign in. In Claude Code,
claude mcp remove envpilotfirst, then add it again without--header. - Delete
ENVPILOT_API_KEYfrom the client's environment if nothing else uses it. - Revoke the old key in Organization → Settings → API Keys, unless it also serves the REST API, the GitHub Action or Docker.
The old key-based setup is documented on API keys (legacy).
Troubleshooting#
| Symptom | Meaning / fix |
|---|---|
| The client never opens a sign-in page and keeps failing with 401 | An Authorization header is still configured, often an old API key. Remove it and restart the client. |
This account belongs to several organizations | Pass organization with one of the slugs the message lists. |
Incompatible auth server: does not support dynamic client registration | The sign-in service is not accepting new clients. Contact support. |
| Signed in, but every call fails with a plan error | The organization's plan does not include the MCP server. |
| Hosted Claude asks for an OAuth client ID or secret | Leave those fields empty and choose Connect. Never paste an API key into an OAuth client-secret field. |
Limits#
- Pro plan (
mcp_server), re-checked on every call. - A connection sees what you see. There is no way yet to give an agent less access than your own role.
- Streamable HTTP only. There is no stdio transport and no local proxy.