Skip to main content
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 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.
  • 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, 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:

​
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 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.

​
Too many tool calls

These limits apply on every plan. They count per person, so every agent and token you connect shares them.
  • “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 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:

​
Common questions

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.
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.
Yes. Any MCP-compatible client can connect to Wonder. Use the manual setup instructions on the Wonder MCP 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.
Head to our Feature Requests board or drop a message in our Discord.

​
If something goes wrong

If none of these fixes it, contact support. Include your client, the exact message your agent showed, and what you asked it to do.
  • Wonder MCP: connect your agent and see what each plan includes.
  • Support: reach the Wonder team.