# MCP server

Source: https://developers.leonai.io/docs/mcp-server/

:::warning[Not published yet]
The MCP server is not on npm yet, and no `@leonai/` package on npm is ours yet — do not
install or run one. Until we publish it, call the REST API directly: see the
[API reference](https://developers.leonai.io/docs/api-reference/) and the [OpenAPI 3.1 spec](https://api.short.leonai.io/api/v1/openapi.json).
The tools below are what the server will expose.
:::

The LeonAI MCP ([Model Context Protocol](https://modelcontextprotocol.io)) server will let
AI assistants — Claude Code, Claude Desktop, Cursor, ChatGPT, and any other MCP client
— create and manage short links, read click analytics, track conversions, build QR
code URLs, list custom domains, and manage link-in-bio pages on your behalf.

Under the hood it is a thin, LLM-friendly layer over the [TypeScript SDK](https://developers.leonai.io/docs/sdks/):
every tool call goes through the SDK, so auth, retries, rate-limit parsing, and typed
errors come for free.

## Requirements

- Node.js >= 18
- A LeonAI API key (dashboard → **Settings → API Keys**)

## Environment variables

| Variable          | Required | Default                       | Description                                                                                  |
| ----------------- | -------- | ----------------------------- | -------------------------------------------------------------------------------------------- |
| `LEONAI_API_KEY`  | yes      | —                             | API key sent as `X-API-Key`. The server exits immediately with a helpful message if missing. |
| `LEONAI_BASE_URL` | no       | `https://api.short.leonai.io` | API origin. Point at staging or a self-hosted deployment.                                    |

## Transport

The server speaks MCP over **stdio**: stdout carries the protocol, logs go to stderr.
Setup for Claude Code, Claude Desktop, Cursor and other clients will be listed here once
the package is published.

## Tool catalog

Fourteen tools are exposed:

| Tool                    | Arguments                                                                    | Description                                                                               |
| ----------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `create_link`           | `url`, `customCode?`, `title?`, `tags?`, `expiresAt?`, `conversionTracking?` | Create a short link (custom back-half, expiry on Pro+, conversion tracking on Business+). |
| `get_link`              | `idOrCode`                                                                   | Full details of one link by short code (destination, tags, UTM, expiry).                  |
| `list_links`            | `search?`, `tags?`, `limit?`, `offset?`                                      | List links with search + tag filters; includes click counts.                              |
| `update_link`           | `id`, `url?`, `title?`, `tags?`, `expiresAt?`                                | Partial update of an existing link.                                                       |
| `delete_link`           | `id`                                                                         | Delete a link (the short URL stops redirecting).                                          |
| `get_link_analytics`    | `linkId`, `startDate?`, `endDate?`                                           | Clicks, unique visitors, timeline, and device/browser/OS/country/referrer breakdowns.     |
| `get_account_analytics` | —                                                                            | Dashboard summary: last 7/30 days plus growth.                                            |
| `get_conversions`       | `linkId`, `startDate?`, `endDate?`                                           | Conversion & revenue report for a link (Business+).                                       |
| `track_conversion`      | `clickId?` or `linkId`, `name`, `value?`, `currency?`, `externalId?`         | Record a conversion; `externalId` makes it idempotent.                                    |
| `build_qr_url`          | `shortCode`, `size?`, `format?`, `color?`                                    | Build the public QR image URL (no API call).                                              |
| `list_domains`          | —                                                                            | Custom branded domains with verification/SSL status.                                      |
| `create_bio_page`       | `slug`, `title`, `bio?`, `avatarUrl?`                                        | Create a link-in-bio landing page.                                                        |
| `list_bio_pages`        | —                                                                            | List bio pages with publish status and item counts.                                       |
| `add_bio_page_item`     | `pageId`, `type`, `title`, `url?`, `linkId?`, `position?`                    | Add a link/header/social item to a bio page.                                              |

Notes:

- All tools return JSON — both as text content and as MCP `structuredContent`.
- Failed API calls return an MCP tool error (`isError: true`) carrying the HTTP
  status, the API's error code and message, and — when present — parsed rate-limit
  headers (`rateLimit`, `retryAfterMs`). The server never crashes on a failed tool call.
- The analytics API reports trailing windows, so `get_link_analytics` converts
  `startDate`/`endDate` into a "last N days" window ending now (default 30 days).

## Resources

| URI                        | Description                                            |
| -------------------------- | ------------------------------------------------------ |
| `leonai://account/summary` | Account analytics dashboard summary (7d/30d + growth). |
| `leonai://links/recent`    | The 20 most recently created links, with click counts. |
| `leonai://domains`         | All custom domains with verification and SSL status.   |

## Local development (this monorepo)

```bash
npm run build -w packages/mcp-server
LEONAI_API_KEY=<your-api-key> node packages/mcp-server/dist/index.js
```