This article is for org admins setting up MCP connections with your team's MCP URL — the recommended way for:
- zeroheight admins/editors,
- viewers who access your design system in zeroheight via SSO,
- private viewers, who sign in with a one-time code sent to their email, and
- guests, who connect without signing in, on styleguides you set to Public
to connect AI tools to the design system context in zeroheight.
Access via link is being deprecated and is only supported while existing connections move to your team's MCP URL. Viewers who can't sign in via SSO can connect as private viewers or guests. Not sure which to use? Start with the zeroheight MCP overview.
Organization settings
Go to Your organization → MCP (or use the zeroheight MCP shortcut in your profile menu).
Access via login is toggled on by default. This means zeroheight admins/editors and viewers who access your design system in zeroheight via SSO can connect AI tools to your organization's styleguides via MCP. Access to individual styleguides is managed at the styleguide level.
The Access via login toggle also covers private viewers and guests. If you turn it off, they can't connect either. Whether guests can connect is set per styleguide, and the Access anonymously column in the MCP styleguide access table shows which styleguides allow it.
Click Edit next to any styleguide in the MCP styleguide access table to manage its settings.
Enable write access under Enable MCP write is also on by default. It lets AI tools connected by admins and editors create and update pages. Viewer connections stay read only. Learn more about writing to zeroheight via MCP.
Styleguide settings
In styleguide settings, go to MCP and select the MCP tab.
By default, Enable this styleguide for MCP is toggled on for each styleguide. The exception is styleguides set to private and password-protected, where it is disabled by default.
Note: this setting also applies to partner connectors like Figma Make. Disabling it blocks those connections too.
This setting doesn't affect connections that use API credentials. See Connect with API credentials (CI/CD) below.
Choose who can connect
Under MCP access, choose who can connect to the styleguide:
- Org only (shown as your team name followed by "org only"): only members of your zeroheight team. Viewers who sign in via SSO can't connect.
- Restricted: admins and editors, viewers who sign in via SSO, and private viewers. This option is only shown if your plan includes private viewers or your team uses SSO.
- Public: everyone above, plus guests. Anyone with your team's MCP URL can connect without signing in. Not available if the styleguide's Website access settings include a password or SSO.
Until you choose an option, a styleguide follows its Website access settings:
- Public if the styleguide has no password or SSO
- Restricted if it has a password or SSO, or Org only if Restricted isn't available on your plan
- Org only if your organization restricts access by IP address
When you change the option, zeroheight asks you to confirm and tells you who will gain or lose access. Turning off Enable this styleguide for MCP resets the option to Org only.
If you add a password or SSO to a Public styleguide, zeroheight warns you and changes its MCP access to Restricted, or Org only if Restricted isn't available on your plan.
Add private viewers
Private viewers can connect to the MCP without a zeroheight account. They sign in with a one-time code sent to their email.
Add them by email under Add private viewers on the MCP tab. You can paste several emails separated by commas, or import them from a CSV file. This is the same list as the styleguide's private viewers, so anyone you add here can also view the styleguide, and anyone you invite as a private viewer from the Share modal can also connect to the MCP.
Private viewers can only connect when MCP access is set to Restricted or Public. If you remove someone from the list, their connection stops at its next request.
Share access with your team
Everyone in your team connects with the same URL, which includes your team subdomain: https://mcp.zeroheight.com/your-subdomain/mcp. You'll find your team's URL under MCP connection details on the MCP tab in styleguide settings, and in the Share modal.
https://mcp.zeroheight.com/mcp also still works. People who connect with it are asked for your team subdomain when they sign in.
But to make sharing access easier, you can add the details to your styleguide using the remote MCP details block.
You can add a Remote MCP details block to a page in your styleguide so that viewers are able to see instructions for connecting to the MCP from the styleguide.
- Open the slash inserter on any page, select Remote MCP details and select Access via login
- Optionally configure which client tabs are visible using the block's settings
-
Optionally turn off Display help message if you're providing your own setup guidance
You can also grab the MCP connection details when you click Share in your styleguide:
Connect the MCP to your AI tool
For Cursor, VS Code, Claude Code, Codex and Kiro, one-click and copy-paste installation commands are available under Styleguide settings → MCP, in the remote MCP details block, and in the Share modal.
If you're using Figma, ChatGPT/Codex or Claude connect via the respective partner connector.
For all other tools, see their documentation:
Claude Code · VS Code + GitHub Copilot · GitHub Copilot CLI · Windsurf · Zed · JetBrains AI · Gemini CLI · Opencode · Amazon Q · Kiro · Copilot Studio · Bolt · Cursor
When you attempt to connect, you'll be redirected to your browser, which opens the Connect to the zeroheight MCP screen and shows which team you're connecting to. If you connected with https://mcp.zeroheight.com/mcp, enter your team subdomain first.
Then choose how to sign in.
Admins, editors and viewers who sign in via SSO: if allowed, admins/editors can log in via username/password or SSO. Viewers must log in via SSO.
- Click Continue with SSO. This button is shown if your team uses SSO. Admins and editors who log in with a username and password click Log in with zeroheight account instead
- Sign in via the SSO provider, or with your username and password
-
Approve the connection
Private viewers:
- Under Have an invite email?, click Continue with email
- Enter the email address you were added with
- Enter the code sent to your email and click Verify. The code is 6 characters, works once, and expires after 10 minutes.
- Approve the connection
Guests: click Continue as guest. This option is only shown if at least one of your team's styleguides allows guests. Then approve the connection.
You'll then be redirected back to the tool you were connecting to.
Connect with API credentials (CI/CD)
Use API credentials when nobody can sign in through a browser, for example in a CI/CD pipeline that reviews every pull request against your design system. For a worked example, see Auditing every pull request against your design system.
Your AI tool connects to the same URL, https://mcp.zeroheight.com/mcp, and sends a zeroheight API Client ID and Access Token as request headers instead of signing in.
- Create a Client ID (starts with
zhci_) and Access Token (starts withzhat_). See the API authentication guide. - Store both as secrets in your CI system, for example as GitHub Actions secrets named
ZEROHEIGHT_CLIENT_IDandZEROHEIGHT_ACCESS_TOKEN. - Add the MCP server to your AI tool with two headers:
X-API-CLIENTset to the Client ID, andX-API-KEYset to the Access Token.
In Claude Code:
claude mcp add --transport http zeroheight https://mcp.zeroheight.com/mcp \ --header "X-API-CLIENT: $ZEROHEIGHT_CLIENT_ID" \ --header "X-API-KEY: $ZEROHEIGHT_ACCESS_TOKEN"
In Codex, add this to config.toml:
[mcp_servers.zeroheight]
url = "https://mcp.zeroheight.com/mcp"
env_http_headers = { "X-API-CLIENT" = "ZEROHEIGHT_CLIENT_ID", "X-API-KEY" = "ZEROHEIGHT_ACCESS_TOKEN" }Connections that use API credentials work differently from signed-in connections:
- They're read only, even if the API token has write scopes.
- They can read private pages.
- The MCP settings for your organization and for each styleguide don't apply to them. They reach every styleguide the API token can access. To stop a connection, revoke its API token.
- The API token belongs to your team, not to the person who created it. Any editor can manage or revoke it.
Security and authentication
Signed-in connections use OAuth 2.1 with PKCE. Each person signs in with their own zeroheight account, either via username/password (admins/editors, if allowed) or via your SSO provider, such as Okta. Signed-in connections don't use a shared API key or long-lived static token. Connections that use API credentials are the exception, and the points below don't apply to them.
Private viewers confirm their email with a one-time code instead of signing in to a zeroheight account. Guests don't sign in, so they only reach styleguides set to Public.
- Per-user access: the AI tool acts as the signed-in person. It can only reach styleguides that person can already see in zeroheight, and only those with Enable this styleguide for MCP turned on and an MCP access option that includes them.
- Short-lived tokens: access tokens for admins and editors expire after 2 hours and are refreshed automatically. Viewers who sign in via SSO get a 7-day session with no refresh. When it ends, they sign in via SSO again. Private viewers and guests also have to reconnect 7 days after they connect.
- Checked on every request: zeroheight re-validates the token and your MCP settings on every call. If you turn off Access via login for your organization or Enable this styleguide for MCP for a styleguide, or remove a user from your team or a private viewer from the list, their connections stop at their next request.
- Read-only for viewers: viewer, private viewer and guest connections can only read documentation. Admins and editors also get the write tools, unless your organization has turned off Enable write access under Your organization → MCP. Learn more.
- Stored securely: zeroheight stores only hashed tokens, never the tokens themselves.
- No private pages for private viewers and guests: their connections can't read pages marked as private.
Connecting to multiple styleguides
When you connect with your team's MCP URL, one connection reaches every styleguide you're allowed to connect to under Styleguide settings → MCP. For guests, that's every Public styleguide. For private viewers, it's every Restricted or Public styleguide they've been added to, plus the ones guests can reach.
If you want viewers who sign in with SSO to have access to different styleguides, check out the documentation for SSO viewer groups.