MCP

What is the TwistCal MCP server?

AI agents like Claude, Cursor, VS Code Copilot, and Windsurf can talk to TwistCal directly. Instead of pasting HTML and hoping the agent figures out the attributes, the agent calls the MCP server to get the config schema, the API reference, and a ready-to-paste install snippet.

The endpoint is https://twistcal.com/mcp (Streamable HTTP). No authentication. It’s read-only, same public docs as the website.

Available tools

Tool	What it does
get_config_schema	Full config schema: all HTML attributes, build variants, 12 supported languages, 25+ CSS custom properties
get_api_reference	Every public export, the web component, declarative triggers, events, helpers, build variants with sizes
generate_snippet	Takes structured event data, returns a CDN script tag + <twist-cal> element or data-twistcal trigger button

Claude Code (terminal)

One command:

claude mcp add --transport http twistcal https://twistcal.com/mcp

This writes to ~/.claude/mcp.json (local scope, default). To make TwistCal available across all your projects:

claude mcp add --transport http --scope user twistcal https://twistcal.com/mcp

Or edit the file manually:

• macOS/Linux: ~/.claude/mcp.json
• Windows: %USERPROFILE%\.claude\mcp.json

{
  "mcpServers": {
    "twistcal": {
      "type": "http",
      "url": "https://twistcal.com/mcp"
    }
  }
}

Claude Desktop (GUI app)

Edit claude_desktop_config.json:

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

{
  "mcpServers": {
    "twistcal": {
      "url": "https://twistcal.com/mcp"
    }
  }
}

Restart Claude Desktop.

Cursor

Create or edit mcp.json:

• Project-scoped: .cursor/mcp.json in your project root
• Global: ~/.cursor/mcp.json

{
  "mcpServers": {
    "twistcal": {
      "url": "https://twistcal.com/mcp"
    }
  }
}

VS Code (Copilot)

Create or edit mcp.json:

• Workspace: .vscode/mcp.json in your project root (commit to share with your team)
• User profile: run “MCP: Open User Configuration” from the Command Palette (Ctrl+Shift+P)

{
  "servers": {
    "twistcal": {
      "type": "http",
      "url": "https://twistcal.com/mcp"
    }
  }
}

Note: VS Code uses "servers" as the root key, not "mcpServers".

Windsurf

Edit mcp_config.json:

• macOS/Linux: ~/.codeium/windsurf/mcp_config.json
• Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

{
  "mcpServers": {
    "twistcal": {
      "serverUrl": "https://twistcal.com/mcp"
    }
  }
}

Connect to any MCP client

The server runs MCP Streamable HTTP in stateless mode. Any client that supports the Streamable HTTP transport can connect to https://twistcal.com/mcp.

Example: generating a snippet

Once connected, ask your agent:

“I need an Add to Calendar button for a product launch webinar on Feb 10, 2026, 2pm to 3:30pm EST. Outline variant, Google + Apple Calendar only, German UI.”

The agent calls generate_snippet with those parameters and returns:

<script defer src="https://cdn.jsdelivr.net/npm/@freshjuice/twistcal@1.0.0/dist/twistcal.de.min.js"></script>

<twist-cal
  title="Product Launch Webinar"
  start="2026-02-10T14:00:00"
  end="2026-02-10T15:30:00"
  timezone="America/New_York"
  lang="de"
  variant="outline"
  calendars="google,ics">
</twist-cal>

Paste it into your page. Done.

Agent discovery

The server publishes an MCP Server Card at /.well-known/mcp/server-card.json for automated agent discovery. The card lists all available tools and the transport endpoint.

Rate limiting

No rate limit. The server is read-only and stateless. If abuse becomes a problem, a Cloudflare rate limiting rule will be added. Open an issue on GitHub if you hit problems.