Skip to main content

Configure your MCP Client

After generating an API token, you need to configure your MCP client to connect to the Widget Builder. Below are setup instructions for popular MCP clients.

Connection details​

All MCP clients need the same two pieces of information:

SettingValue
Server URLhttps://app.widgetbuilder.de/api/mcp
Authorization HeaderBearer wb_your_token_here
tip

If you are running the Widget Builder locally for development, use http://localhost:7071/api/mcp as the server URL.

Claude Desktop​

Claude Desktop by Anthropic supports MCP servers natively.

1. Open the configuration file​

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the Widget Builder MCP Server​

{
  "mcpServers": {
    "widget-builder": {
      "type": "http",
      "url": "https://app.widgetbuilder.de/api/mcp",
      "headers": {
        "Authorization": "Bearer wb_your_token_here"
      }
    }
  }
}

3. Restart Claude Desktop​

Close and reopen Claude Desktop. You should see the Widget Builder tools available in the tool list (hammer icon).

Claude Code (CLI)​

Claude Code supports MCP servers through its settings file.

1. Open the settings file​

The settings file is located at ~/.claude/settings.json.

2. Add the Widget Builder MCP Server​

{
  "mcpServers": {
    "widget-builder": {
      "type": "http",
      "url": "https://app.widgetbuilder.de/api/mcp",
      "headers": {
        "Authorization": "Bearer wb_your_token_here"
      }
    }
  }
}

3. Restart Claude Code​

Start a new Claude Code session. The Widget Builder tools will be available automatically.

Cursor​

Cursor supports MCP servers through its settings.

1. Open Cursor Settings​

Go to Cursor Settings > MCP or create/edit the file .cursor/mcp.json in your project root.

2. Add the Widget Builder MCP Server​

{
  "mcpServers": {
    "widget-builder": {
      "type": "http",
      "url": "https://app.widgetbuilder.de/api/mcp",
      "headers": {
        "Authorization": "Bearer wb_your_token_here"
      }
    }
  }
}

3. Restart Cursor​

Restart the editor to activate the MCP connection.

Windsurf​

Windsurf supports MCP servers through its configuration.

1. Open the MCP configuration​

Go to Windsurf Settings > Cascade > MCP or edit ~/.codeium/windsurf/mcp_config.json.

2. Add the Widget Builder MCP Server​

{
  "mcpServers": {
    "widget-builder": {
      "type": "http",
      "url": "https://app.widgetbuilder.de/api/mcp",
      "headers": {
        "Authorization": "Bearer wb_your_token_here"
      }
    }
  }
}

3. Restart Windsurf​

Restart the editor to activate the connection.

Other MCP Clients​

Any MCP-compatible client that supports HTTP-based MCP servers (Streamable HTTP transport) can connect to the Widget Builder. The key requirements are:

  1. Protocol: MCP 2025-03-26 (JSON-RPC 2.0 over HTTP)
  2. Endpoint: POST https://app.widgetbuilder.de/api/mcp
  3. Content-Type: application/json
  4. Authorization: Bearer token in the Authorization header

Verifying the connection​

Once configured, you can verify the connection by asking your AI assistant:

"List my Widget Builder widgets"

If the connection is working, the assistant will return a list of your widgets.

Troubleshooting​

IssueSolution
"Unauthorized" or 401 errorCheck that the token is correct and starts with wb_
"Token expired" errorGenerate a new token in the Widget Builder app
Connection timeoutVerify the server URL is correct and reachable
Tools not appearingRestart the MCP client after updating the configuration
"Token revoked" errorThe token has been revoked; generate a new one

Next steps​

Now that your MCP client is connected, explore the available tools to see what you can do.