Connect Windsurf and other MCP clients with an API key

Claude, Claude Code and Cursor can connect to Wuizard by signing in with your account, and that's the easiest route for them: the main connection guide covers it. Every other MCP client, Windsurf included, connects with a personal API key: a secret you put in the client's config so it can call the Wuizard MCP server as you.

A key is also the way to connect Claude Code or Cursor where a browser sign-in isn't practical, such as a remote machine you reach over SSH. This guide covers creating the key, the config for each kind of client, checking the connection and rotating the key later.

Before you start#

• A Wuizard account with a sheet. If you haven't made one yet, design a sheet or describe your app to the designer first.
• An MCP client that can add a remote server over HTTP and send a request header with it. Most current clients can; check yours if you're unsure.

Create your key#

1. In Wuizard, open Agents. The agents row at the foot of the sidebar opens a panel with a link there.
2. Find Personal API key and click Create key.
3. Copy the key from the Your new API key window. It starts with wz_sk_.

Next to the key you'll see when it was last used, which is handy later for checking that a client is really using it.

Keep the key in your environment#

The configs below read the key from an environment variable called WUIZARD_KEY, so it never has to be pasted into a file you might share. On macOS or Linux, add a line like this to your shell profile and open a new terminal:

export WUIZARD_KEY="wz_sk_your_key_here"

Apps you open from the dock or a launcher may not see variables from your shell profile. If a client can't find the key, start it from a terminal, or put the key directly in its config as described below.

Windsurf with a key#

Open Windsurf's MCP config file, mcp_config.json (Windsurf's docs give its location), and add the Wuizard server:

{
  "mcpServers": {
    "wuizard": {
      "serverUrl": "https://wuizard.com/mcp",
      "headers": { "Authorization": "Bearer ${env:WUIZARD_KEY}" }
    }
  }
}

Windsurf fills in ${env:WUIZARD_KEY} from your environment, so the file itself holds no secret. Save it, then refresh Windsurf's MCP servers or restart it.

Any other client#

Open your client's MCP config file (its docs say where it lives) and add the Wuizard server:

{
  "mcpServers": {
    "wuizard": {
      "url": "https://wuizard.com/mcp",
      "headers": { "Authorization": "Bearer $WUIZARD_KEY" }
    }
  }
}

Save the file and restart the client, or reload its MCP servers if it has a button for that. Some clients fill in $WUIZARD_KEY from your environment. If yours doesn't, replace $WUIZARD_KEY with the key itself, keeping the word Bearer and the space in front of it, and keep that file out of version control.

The Agents page has the exact config for each agent it lists, with a copy button: open your agent's card and pick API key.

Claude Code with a key#

Run this in your project folder:

claude mcp add --transport http wuizard https://wuizard.com/mcp \
  --header "Authorization: Bearer $WUIZARD_KEY"

Your shell fills in the key when you run the command, so Claude Code stores the key itself in its config. If you rotate the key later, remove the server with claude mcp remove wuizard and add it again.

Cursor with a key#

Create .cursor/mcp.json in your project, or add to it if it exists:

{
  "mcpServers": {
    "wuizard": {
      "url": "https://wuizard.com/mcp",
      "headers": { "Authorization": "Bearer ${env:WUIZARD_KEY}" }
    }
  }
}

Cursor reads the key from your environment through ${env:WUIZARD_KEY}, so the file itself holds no secret.

Check the connection#

Start a new conversation in your client and ask:

Call list_sheets, then get_sheet, and tell me which sheet is active.

A connected agent lists your sheets and summarises the active one: its colours, fonts, radius, motion spring, the slots you've filled and your rules. Back in Wuizard, the key's last used time updates, and the Tools your agent gets table on the same page counts each tool's calls over the last seven days.

If the agent answers from general knowledge or says it has no Wuizard tools, see troubleshooting below.

What the key can do#

A personal key acts as you over MCP. Your agent can read every sheet you own, fetch tokens, slots, pages and library assets, and use the tools that change things:

• add_to_sheet puts an asset you've chosen into a slot.
• generate_media makes an image or animation and saves it to the sheet. See generating images and animations.
• create_sheet_from_extraction saves a website extraction as a new sheet, once you agree.

add_to_sheet and create_sheet_from_extraction tell the agent to ask you first, and generate_media asks it to check with you before making several. The metered tools cost the same for every connection, so check the usage limits before you let an agent loose on a long task.

Rotate or revoke a key#

On Agents, click Regenerate under your key and confirm. A new key is created and the old one stops working straight away. Update WUIZARD_KEY (and any config that holds the key itself), then restart your clients.

Signed-in apps such as Claude or Cursor aren't affected by this. They appear in the Agents list on the same page, each with a Disconnect button that revokes its access at once.

Troubleshooting#

Still stuck? Email support from the docs page and a person replies.

Where to go next#

With the agent connected, put your sheet's CLAUDE.md or AGENTS.md in the repo so every session starts on your design system: the export guide explains what's in it. The full list of tools is in the docs.