# Hovercode MCP Server

> Manage your Hovercode QR codes from any MCP client — Claude, Cursor, or your own agent — by chatting.

Endpoint: `https://hovercode.com/mcp/`
Transport: HTTP (JSON-RPC 2.0)
Auth: Bearer token — your Hovercode API token

---

## What it does

The Hovercode MCP server lets an AI assistant work with your real workspace:
create QR codes with full design control, retarget a dynamic code's destination,
search your codes, and read scan analytics — all conversationally. Anything the
assistant creates lands in your Hovercode dashboard.

This is different from the Hovercode app inside ChatGPT (which makes one-off
anonymous codes). This server acts on *your account*.

---

## Authentication

Two ways to connect:

**1. OAuth (recommended for connectors).** In Claude.ai, ChatGPT, or any client
that supports remote MCP connectors, just add the server URL
`https://hovercode.com/mcp/` and click connect — the client registers itself and
sends you through a normal Hovercode login + approval screen. No token to copy.

**2. API token (for CLI/config clients).** Authenticate with your Hovercode API
token as a bearer token — find it at https://hovercode.com/api/.

```
Authorization: Bearer YOUR-API-TOKEN
```

Both `Bearer <token>` and `Token <token>` are accepted. Creating dynamic
(editable, tracked) codes requires a paid plan; static codes are always
available.

---

## Connect

### Claude Code

```
claude mcp add --transport http hovercode https://hovercode.com/mcp/ \
  --header "Authorization: Bearer YOUR-API-TOKEN"
```

### Claude Desktop / other clients (config)

```json
{
  "mcpServers": {
    "hovercode": {
      "type": "http",
      "url": "https://hovercode.com/mcp/",
      "headers": { "Authorization": "Bearer YOUR-API-TOKEN" }
    }
  }
}
```

### Cursor

Add an HTTP MCP server pointing at `https://hovercode.com/mcp/` with an
`Authorization: Bearer YOUR-API-TOKEN` header.

---

## Tools

| Tool | What it does |
|------|--------------|
| `list_workspaces` | List your workspaces and their ids; the current (default) one is marked. |
| `set_workspace` | Switch the current (default) workspace by id or name. New codes go here unless told otherwise. |
| `create_qr_code` | Create a QR code. Supports colors, pattern, eye style, frames with captions, logos, templates, and `dynamic: true` for editable + tracked codes. Returns a rendered preview. |
| `create_qr_codes_bulk` | Create many QR codes at once from a list of URLs, all sharing a design. |
| `create_pdf_qr` | Host a PDF (by URL or base64) and get a dynamic QR + short link for it. Swap the PDF later without reprinting. |
| `get_qr_code` | Get one code's details and a preview, plus total and unique scan counts. |
| `get_analytics` | Scan analytics over a period (totals, by-day, top countries/cities/OS/browsers) for one code or the whole workspace. |
| `download_qr` | Get print-ready image links (high-res PNG + vector SVG) for a code. |
| `list_qr_codes` | List/search codes in a workspace. |
| `update_qr_code` | Retarget a dynamic code's destination, **restyle it in place** (colors/pattern/eye style/frame/logo, without replacing the code), rename it, or toggle location tracking. Returns the re-rendered preview. |
| `delete_qr_code` | Delete a code. |
| `get_qr_activity` | List recent scan events (time, location, device) for a dynamic code. |
| `list_templates` | List saved design templates to reuse your branding. |
| `create_form` | Build a form from a list of fields, brand it (theme/colors/logo), publish it, and get back a share link + QR. Set a redirect URL to send respondents somewhere after they submit. |
| `update_form` | Change an existing form without recreating it: edit fields, settings (redirect/thank-you/title), or branding, or close/reopen it. |
| `list_forms` / `get_form` | Find forms and read their status, response count, link, and QR. |
| `get_form_responses` | Read a form's submissions so the assistant can summarize them. |
| `create_page` | Create a micro landing page (title + links) and get its live URL + QR. |
| `list_pages` / `get_page` | Find landing pages and read their details. |
| `create_short_link` | Shorten a URL (custom slug/domain optional); returns the short link + QR. |
| `update_short_link` | Retarget a short link, rename it, or toggle location tracking. |
| `list_short_links` / `get_short_link` | Find short links and read their click counts. |
| `get_short_link_activity` | List click events (time, location, device) for a short link. |
| `delete_short_link` | Delete a short link. |

---

## Example prompts

- "Create a dynamic QR code for https://example.com/summer with our brand
  colors and the caption SCAN ME."
- "Here's a link to our menu PDF — turn it into a QR code for the table tents."
- "Make a form to collect name, email, and t-shirt size, and give me a link and QR to share it."
- "Summarize this week's responses to my feedback form."
- "Make a landing page with my Instagram, shop, and booking links, and a QR for the window."
- "Point my 'menu' QR code at the new PDF at https://example.com/menu-fall.pdf."
- "Restyle my event QR to our brand colors with rounded eyes — same code, don't replace it."
- "Make a form that asks for a name and email, then redirects to go.co on submit."
- "Make my signup form match our brand: dark theme, gold button, and our logo."
- "Add a phone field to my event form and make email required."
- "Close my feedback form — we've got enough responses."
- "Switch to my Acme workspace."
- "How did my QR codes do this month, and where were people scanning them?"
- "Make QR codes for all 20 of these product URLs in our brand colors."
- "Give me a print-ready PNG of my event QR."
- "List all my QR codes that mention 'event'."

---

## Notes

- Every workspace-scoped tool defaults to your only workspace; if you have
  several, pass a `workspace` id (use `list_workspaces` to find it).
- Design edits aren't supported on an existing code — recreate it to restyle.
- Errors come back as readable messages so the assistant can correct itself.