---
title: "MCP"
url: "https://twistcal.com/docs/mcp"
description: "Connect AI agents to TwistCal via MCP. Get the config schema, API reference, and generate install snippets programmatically."
---

## 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](https://github.com/nousresearch/modelcontextprotocol?utm_source=twistcal.com) 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](https://github.com/freshjuice-dev/twistcal/issues?utm_source=twistcal.com) if you hit problems.