# FlipLetters

> FlipLetters (https://flipletters.com) makes split-flap / flip-dot board videos
> with synthesized mechanical click sound. Boards are defined in "flipcode" —
> a small open text format (like Markdown for flap displays). Editor:
> https://app.flipletters.com · Spec: https://flipletters.com/docs

## For AI agents (read this first)

Setup for Cursor, Claude, ChatGPT, Grok and other MCP clients: https://flipletters.com/connect
Hosted MCP supports OAuth 2.1 (PKCE S256, dynamic client registration, Google sign-in): clients that support MCP auth just add https://app.flipletters.com/mcp/v1 and click Connect. Metadata: https://app.flipletters.com/.well-known/oauth-protected-resource/mcp/v1

You can draft flipcode with the library or local stdio MCP with **no account,
no payment, and no API key**. Hosted HTTP MCP at
https://app.flipletters.com/mcp/v1 requires `Authorization: Bearer flk_…` for
every tools/call. A signed-in human mints a key (free) in Studio → Account →
API keys & agents. Your job is to produce valid flipcode and a Studio URL; the
human previews and exports under their plan.

### npm packages

| Package | Install | Role |
|---|---|---|
| @flipletters/flipcode | `npm i @flipletters/flipcode` | MIT parser/serializer (zero deps) |
| flipletters-mcp-server | `npx -y flipletters-mcp-server` | Local MCP tools (stdio). Also hosted: https://app.flipletters.com/mcp/v1 |

- npm: https://www.npmjs.com/package/@flipletters/flipcode
- npm: https://www.npmjs.com/package/flipletters-mcp-server
- GitHub (flipcode): https://github.com/tera-sarah/flipcode
- Contact on packages: FlipLetters <dev@flipletters.com>

### MCP — hosted Streamable HTTP (Cursor / remote clients)

```json
{
  "mcpServers": {
    "flipletters": {
      "url": "https://app.flipletters.com/mcp/v1",
      "headers": {
        "Authorization": "Bearer flk_…"
      }
    }
  }
}
```

URL: https://app.flipletters.com/mcp/v1 (/mcp redirects here; legacy alias /api/mcp still works)
Discovery: https://app.flipletters.com/.well-known/mcp/server.json
GET is a descriptor (no key). Every hosted `tools/call` requires
`"headers": { "Authorization": "Bearer flk_…" }`.

### MCP — local stdio

```json
{
  "mcpServers": {
    "flipletters": {
      "command": "npx",
      "args": ["-y", "flipletters-mcp-server"]
    }
  }
}
```

### MCP tools

Draft / share (hosted HTTP: Bearer flk_…; local stdio: no key):
1. `flipletters_flipcode_reference` — cheat sheet; call before writing
2. `flipletters_example_board` — known-good starting board by type
3. `flipletters_validate_board` — normalize + warnings + **share URL**
4. `flipletters_template_url` — readable `?board=…&slide=…` URLs

Cloud (same flk_… key; stdio: FLIPLETTERS_API_KEY from Studio Account → API keys & agents):
0. `flipletters_create_animation` — text (+ optional template) → moderated, watermarked-on-free MP4: returns mp4Url, shareUrl, jobId, status, expiresAt
5. `flipletters_render_board` — cloud MP4 under key owner's plan
6. `flipletters_render_status` — poll job
7. `flipletters_list_teams` — teams the owner belongs to
8. `flipletters_share_to_team` — push board into Team Library
9. `flipletters_list_workspaces` — agency projects for the key owner
10. `flipletters_list_postiz_destinations` — Postiz share accounts on a project
11. `flipletters_list_postiz_integrations` — channels on a Postiz destination
12. `flipletters_share_to_postiz` — upload media + schedule/draft/post on Postiz

Loop: reference → write flipcode → validate → deliver share link.
Optional: render, share_to_team, or share_to_postiz with API key.

### Without MCP

Write flipcode (below) and return one of:

- Readable params (each mirrors a flipcode line; `|` separates rows):
  https://app.flipletters.com/?board=station&grid=8x34&title=DEPARTURES&slide=ROW ONE|ROW TWO&flip=cascade,11&hold=6
- Full fidelity (base64url flipcode in the fragment):
  https://app.flipletters.com/#code=<base64url>

### flipcode in 12 lines

```
flipletters v1
board: trainboard 8x34      # minimal|trainboard|artboard|flipdot|marquee|announcement|arena + ROWSxCOLS
output: 1920x1080 30fps     # or vertical / square / 4k, or 1200x630@25
title: DEPARTURES           # station, announcement, and arena boards
footer: LAKERS.COM | TICKETS # arena marquee footer bar
accent: #ffb63d
sound: solari volume 0.8    # solari|thock|deep|clickity|fizz|none

--- slide 1
hold: 5s
flip: cascadeRows 11/s jitter 0.2 stagger 0.4
| ONE ROW OF UPPERCASE BOARD TEXT
| ANOTHER ROW
```

Transitions: allAtOnce, cascadeRows, sweepColumns, randomDissolve, wave,
diagonal, radial, spinStop. No fades or zooms — flip-native equivalents only.
Parsers are forgiving: out-of-range values clamp with warnings; unknown lines
are ignored. Only empty documents error.

### Free vs paid (agents)

| Action | Cost |
|---|---|
| Draft / validate flipcode (library or local stdio MCP) | Free forever (no key) |
| Hosted HTTP MCP tools/call | Free key (signed-in human) |
| Share / open-with-code Studio URL | Free |
| Human preview with sound | Free |
| Create API key (Studio Account → API keys & agents) | Free (signed-in human) |
| Human / agent cloud MP4 export | Free quota then paid plans (same entitlements) |
| Create a Team workspace | Premium human |
| Join a team by invite | Free |
| Agent cloud render / team share with key | Uses human’s plan; key from Account |

Local stdio MCP draft tools need no key. Hosted HTTP MCP requires `flk_…` for
every tools/call. A human creates the key in app.flipletters.com → Account →
API keys & agents (shown once). Full plans: https://flipletters.com/pricing

## Billing (humans)

Creating and drafting are free. Exporting MP4s: 5 free watermarked exports,
then $1.99/single export, Premium $8.99/mo (no watermark, Pro templates, 4K,
teams), Studio $29.99/mo (long ambience renders, own audio, TikTok posting).

## How-to (quick)

1. Studio: open https://app.flipletters.com → </> Code → paste flipcode → Apply → Export
2. Library: `npm i @flipletters/flipcode` → parseFlipcode → encodeFlipcodeForUrl → share URL
3. Agent: hosted MCP `https://app.flipletters.com/mcp/v1` or `npx -y flipletters-mcp-server` → reference → write → validate → share URL
4. No tools: write flipcode from this file / /docs and return a ?board=…&slide=… URL

Full how-to: https://flipletters.com/docs#how-to
GitHub (source + HOWTO.md + examples): https://github.com/tera-sarah/flipcode

## FlipLetters developer resources

Predictable URLs (search “FlipLetters”):

| Resource | URL |
|---|---|
| Agent summary (this file) | https://flipletters.com/llms.txt |
| flipcode spec | https://flipletters.com/docs |
| FlipLetters HTTP API | https://flipletters.com/docs/api |
| OpenAPI 3 (JSON) | https://flipletters.com/openapi.json |
| OpenAPI 3 (YAML) | https://flipletters.com/api/openapi.yaml |
| FlipLetters MCP server | https://flipletters.com/mcp |
| Sitemap | https://flipletters.com/sitemap.xml |
| Studio | https://app.flipletters.com |

There are **no public partner webhooks**. Stripe and TikTok callbacks are internal Studio integrations.

Auth notes: https://flipletters.com/docs/api — `Authorization: Bearer flk_…` or a Firebase ID token. Keys are created by a human in Studio → Account → API keys & agents.

## Key pages

- https://flipletters.com — FlipLetters home
- https://flipletters.com/docs — FlipLetters flipcode spec + how-to + npm + agent guide
- https://flipletters.com/docs/api — FlipLetters HTTP API
- https://flipletters.com/docs#how-to — step-by-step how-to
- https://flipletters.com/docs#for-agents — agent section
- https://flipletters.com/docs#npm-packages — package section
- https://flipletters.com/mcp — FlipLetters MCP (hosted HTTP + stdio)
- https://app.flipletters.com/mcp/v1 — hosted Streamable HTTP MCP
- https://app.flipletters.com/api/mcp — legacy alias of the hosted MCP
- https://flipletters.com/openapi.json — OpenAPI 3
- https://github.com/tera-sarah/flipcode — public repo (spec + parser)
- https://github.com/tera-sarah/flipcode/blob/main/HOWTO.md — how-to on GitHub
- https://flipletters.com/templates — template gallery (free ones show full code)
- https://flipletters.com/pricing — plans
- https://app.flipletters.com — the Studio (editor)