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​

On a 401 response, the server returns a JSON-RPC error whose data.reason is one of missing_credentials, invalid_token, token_revoked, or token_expired. The data.hint points you to the Widget Builder settings page.

The response also carries a WWW-Authenticate header. The error= value is RFC 6750-compliant (invalid_request for missing_credentials, invalid_token for all other auth failures), and a non-standard reason= parameter carries the same fine-grained reason as data.reason, for example:

WWW-Authenticate: Bearer error="invalid_token", error_description="…", reason="token_expired"

so clients can route on the header alone without parsing the JSON-RPC body.

data.reasonMeaningSolution
missing_credentialsNo Authorization: Bearer <token> header was sentConfigure the MCP client with a token
invalid_tokenThe token is not recognized on this server (deleted, or from a different instance)Generate a new token in Widget Builder → Settings → MCP API Tokens
token_revokedThe token was explicitly revokedGenerate a new token
token_expiredAn expiry date was set on the token and it has passedGenerate a new token (or omit expiresAt to make it non-expiring)
Connection timeout—Verify the server URL is correct and reachable
Tools not appearing—Restart the MCP client after updating the configuration

Tokens created without an expiresAt value do not expire. If an MCP client tells you "the token expired" on a non-expiring token, re-check the server response — the actual reason is most likely invalid_token (the token is not in this server's database) rather than token_expired.

Next steps​

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