> ## Documentation Index > Fetch the complete documentation index at: https://wonder.design/docs/llms.txt > Use this file to discover all available pages before exploring further. # Wonder MCP troubleshooting > Fix the problems people hit when connecting an agent to Wonder MCP, from a server that won't show up to the limits on tool calls. Fix the problems people hit most when they connect an agent to Wonder MCP. Find the heading that matches what you see, or the message your agent passes on. **Before you start** · Any MCP client · Free plan ## Wonder isn't showing up in my agent Fully quit and restart your agent. Most MCP connection issues resolve after a restart. If Wonder still doesn't appear, check that the server URL is `https://mcp.wonder.so/mcp`, then follow the [setup steps for your client](https://wonder.design/docs/wonder-mcp.md#install) again. In Claude Code run `claude mcp list`, and in Codex run `codex mcp list`, to see whether Wonder is registered. ## The agent isn't using Wonder The agent doesn't know to look at your Wonder designs. Be explicit in your prompt, for example: *"Use the Wonder MCP to pull my designs and generate the landing page layout."* Most agents discover the available tools automatically, but a nudge helps. ## Could not connect to Wonder Wonder shows this page in your browser when it can't finish signing you in. Return to your agent and start the connection again: in Claude Code, run `/mcp` and authenticate Wonder; in Cursor, click **Authenticate** next to Wonder. Other clients show a sign-in prompt or button. ## Wonder keeps asking me to sign in, or won't connect Every request to Wonder MCP needs you to be signed in, so your sign-in is missing, has expired, or your client isn't sending it. * **Sign in again.** Use the same steps as in [Could not connect to Wonder](#could-not-connect-to-wonder). * **Update your client.** Agents keep you signed in by refreshing your sign-in in the background. That needs Cursor 2.5 or later, Claude Code 2.1.63 or later, or another client that follows the MCP sign-in standard. On older versions you're asked to sign in again more often. * **Choose OAuth.** If your client asks how to authenticate, pick OAuth. Wonder doesn't accept connections without authentication, so an option like **No authentication** won't connect. * **Check your personal access token.** If you connect with a token instead, it may have expired or been deleted. Create a new one in Wonder under **Settings > Account > Personal access tokens**. Tokens last at most a year. ## I don't have a Wonder account yet You need a Wonder account to use Wonder MCP. [Sign up for free](https://app.wonder.so/), then connect your agent and sign in. You don't need to create a file first: your agent can create one for you. The agent only sees the workspaces and files your account can access. ## The agent can read but not edit Your agent can read a file but is refused when it tries to change it. It passes on one of these messages: | Message | What to do | | - | - | | You can view this workspace but not edit it. | You're a viewer. Ask the workspace's owner for an editor seat. | | This workspace is on the free plan. Only the owner can edit … | On Free, only the owner can edit. Ask the owner to upgrade the workspace to Pro. | | This is a public file of an organization you don't belong to, so it is read-only here. | Ask to join that workspace. | | … this token holds reader access to it. | Your personal access token can only read this workspace. Create a token with **Write** turned on for it. | | This token is not scoped to this workspace. | Create a token that includes this workspace. | | This workspace is locked, so nothing in it can change. | [Contact support](https://wonder.design/docs/support.md) to unlock it. | ## Your agents have made 3,000 layers this week On the Free plan, the layers your agents create count toward 3,000 AI-generated layers a week, across all your Free workspaces. Once your agents reach 3,000, new requests can't add layers until the week resets. A request your agent has already started still finishes. The message names when it resets. Your week is the 7 days counted from when you created your account, not a calendar week. Your agent can still read, rename and delete in the meantime. To keep going, upgrade the workspace to [Pro](https://wonder.design/pricing) for unlimited layers. The message links to the workspace's billing settings. ## Generating images or vectors needs an active paid plan Generating images and vectors needs Pro. The workspace's owner can upgrade it in **Settings > Plan & billing**, or fix its payment there if it's already on Pro. On Pro, each person has a monthly allowance in each workspace. When it and the workspace's credits are used up, the message names the date it resets. If you need more sooner, [contact support](https://wonder.design/docs/support.md). ## Too many tool calls These limits apply on every plan. They count per person, so every agent and token you connect shares them. | Limit | Value | | - | - | | Tool calls a minute | 120 | | Tool calls running at once | 8 | | Time for one tool call | 10 minutes | * **"You are sending tool calls faster than the per-user limit of 120 per minute"**: wait a minute. Agents usually wait and continue on their own. Running several agents at once uses up the limit faster. * **"You already have 8 tool calls in flight"**: wait for one to finish. Ask your agent to make its calls one after another instead of in parallel. * **"The request timed out."**: part of the call may already have been applied. Ask your agent to check the file before it tries again, so nothing is applied twice. ## Codex uses Computer Use instead The **Wonder · Computer use** entry requests desktop automation. Follow the [Codex setup](https://wonder.design/docs/wonder-mcp.md#codex) to select the installed Wonder plugin in a new chat, then run the read-only connection check. If MCP is unavailable or sign-in fails, resolve that connection problem before asking Codex to edit your canvas. ## Using Wonder alongside other MCP servers MCP servers run independently, so Wonder won't conflict with them. Add the Wonder config alongside your existing `mcpServers` entries in the same JSON object: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "mcpServers": { "wonder": { "url": "https://mcp.wonder.so/mcp" }, "other-server": { "url": "https://example.com/mcp" } } } ``` ## Common questions > [accordion] What does the Wonder MCP server do? > > The Wonder MCP gives your AI coding agent direct access to your designs, components, and documentation inside Wonder. Instead of screenshotting or describing your designs, your agent can read the actual design data and generate code that matches what you've built on the canvas. > [accordion] Can the agent modify my designs? > > Yes. The Wonder MCP server provides both read and write access. Your agent can pull your designs as context and push new designs or updates back to the canvas. > [accordion] Does it work with Windsurf, VS Code Copilot, or Cline? > > Yes. Any MCP-compatible client can connect to Wonder. Use the manual setup instructions on the [Wonder MCP](https://wonder.design/docs/wonder-mcp.md#other-mcp-clients) page. The JSON config with `"url": "https://mcp.wonder.so/mcp"` works with most clients. For clients that don't support remote URLs directly, use the `mcp-remote` bridge method shown there. > [accordion] Where can I report issues or request features? > > Head to our [Feature Requests board](https://wonderdesign.featurebase.app/en) or drop a message in our [Discord](https://discord.gg/HHA2sq6XKp). ## If something goes wrong If none of these fixes it, [contact support](https://wonder.design/docs/support.md). Include your client, the exact message your agent showed, and what you asked it to do. ## Related * [Wonder MCP](https://wonder.design/docs/wonder-mcp.md): connect your agent and see what each plan includes. * [Support](https://wonder.design/docs/support.md): reach the Wonder team. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.