Link shortener MCP server: Brevily for AI tools

Connect Claude Code, Cursor or any MCP client to Brevily's link shortener MCP server with an API key: nine tools for links and QR codes, with safe retries.

On this page
  1. How Brevily's link shortener MCP server works
  2. Make an API key for your AI tool
  3. Connect Claude Code, Cursor and other MCP clients
  4. The nine MCP tools and their arguments
  5. Create a short link through the MCP server
  6. Safe retries with idempotency_key
  7. Common questions
  8. Next steps

A link shortener MCP server lets an AI assistant make your short links while you work: ask Claude Code for a link to the new pricing page on your own domain, and it calls Brevily and answers with the short URL. Brevily's MCP server is one HTTP address, https://console.brevily.com/api/mcp, reached with an API key in the request headers. It gives the assistant nine tools over links and their QR codes, and the assistant can do no more than its key allows.

Before you start: you need an API key; signing a request shows how to make one. API access, and so the MCP server, depends on your plan (pricing). Keep API errors open for the limits that apply.

The Model Context Protocol (MCP) is how AI tools such as Claude Code and Cursor discover and call outside tools. Brevily's server speaks it over plain HTTP, so there's nothing to install:

  • Address: POST /api/mcp on the console. There's no organisation code in it: the key says which organisation the assistant works in.
  • Transport: MCP's Streamable HTTP, stateless. Each POST carries one JSON-RPC 2.0 message and gets one answer. There's no session id and no event stream; a GET answers 405.
  • Credential: the key's ID in x-api-key and its secret in x-api-secret, as on any API call. There's no OAuth sign-in, so a client that can only connect through OAuth, or only over stdio, can't connect yet.
  • Protocol revisions: 2025-06-18, 2025-03-26 and 2024-11-05.

Each tool runs the console's own code for that action. Every check a person's click runs, the destination's safety check included, runs for the assistant too.

Make an API key for your AI tool

  1. Open Access › API keys and, under Organisation keys, choose New key. For your own scripts, a personal key from Your account › Personal API keys works too.
  2. Give it a Label after the tool, such as "Claude Code, laptop", so you know what to revoke later.
  3. Under Permissions, give Links with View and Create. Add Edit if the assistant may change or disable links, or style their QR codes.
  4. Enter your Current password, choose Create key, and copy the secret: it's shown once.

Permissions follow the key

Every tool is judged exactly as the API route behind it would judge the key:

  • An organisation key has the permissions it was given, and keeps them when the person who made it leaves.
  • A personal key acts as you, within what you can do right now, and sees only the folders you can see.
  • Your plan applies on top. A field your plan doesn't include, such as a password or a path, is refused on that field.
  • Calls count against your organisation's API limits, per minute and per day, shared with every other key.

Connect Claude Code, Cursor and other MCP clients

Keep the key in shell variables, so nothing secret lands in a file you share:

bash
API=https://console.brevily.com/apiKEY=brv_ak_…         # the key's IDSECRET=…             # its secret

The console's own guide, under the ? menu › MCP server (/docs/mcp), shows the same snippets with your console's address filled in.

[screenshot: the console's ? menu › MCP server page, with the server address and the Claude Code command]

Claude Code

One command adds the server with the key's two headers:

bash
claude mcp add --transport http brevily "$API/mcp" \  --header "x-api-key: $KEY" \  --header "x-api-secret: $SECRET"

Cursor, Windsurf and other clients configured by JSON

Clients that take an mcpServers entry with a url and headers, such as Cursor's mcp.json, take this:

json
{  "mcpServers": {    "brevily": {      "url": "https://console.brevily.com/api/mcp",      "headers": {        "x-api-key": "<the key's ID>",        "x-api-secret": "<its secret>"      }    }  }}

Keep the secret out of shared files: a project's MCP file is often committed with the code. Keep the key in a config file that stays on your machine, and revoke the key if it leaks.

Your own MCP client

The first message is initialize, then tools/list and tools/call. A notification such as notifications/initialized answers 202 with no body, and ping answers an empty result.

bash
curl -X POST "$API/mcp" \  -H "x-api-key: $KEY" \  -H "x-api-secret: $SECRET" \  -H "content-type: application/json" \  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize",       "params": {"protocolVersion": "2025-06-18",                  "capabilities": {},                  "clientInfo": {"name": "my-agent", "version": "1.0"}}}'
json
{  "jsonrpc": "2.0",  "id": 1,  "result": {    "protocolVersion": "2025-06-18",    "capabilities": { "tools": { "listChanged": false } },    "serverInfo": { "name": "Brevily", "title": "Brevily", "version": "…" },    "instructions": "Brevily makes short links on your own domain. Start with list_domains …"  }}

Then ask for the tools. The answer lists each one with its arguments as a JSON Schema:

bash
curl -X POST "$API/mcp" \  -H "x-api-key: $KEY" \  -H "x-api-secret: $SECRET" \  -H "content-type: application/json" \  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

Send one message per request: a batch (a JSON array) is refused. An unknown method or tool is a JSON-RPC error.

The nine MCP tools and their arguments

Each tool needs one permission of the key. Its answer carries the data twice: as text for any client, and as structuredContent for one that reads JSON.

  • list_domains (Links · View): the domains links can be made on, your own and the shared ones, which is the default, and how many links your plan has left this period. No arguments.
  • check_back_half (Links · Create): whether a back-half is free on a domain, by the rules a create applies. Takes domain (blank for the default), slug and path.
  • create_link (Links · Create): makes a link and answers its id and short URL. Only url is required; the arguments are below.
  • get_link (Links · View): one link by id, with its settings, state and last 30 days of clicks, visitors and QR scans, as far back as your plan keeps.
  • list_links (Links · View): your links, newest first, 25 a page. Takes query, state (ACTIVE, SCHEDULED, EXPIRED, DISABLED or FLAGGED), domain, path and page.
  • update_link (Links · Edit): changes a link by id. A field left out keeps its value, an empty string clears it (except url), and clearPassword: true removes the password. The domain, back-half and path never change.
  • set_link_status (Links · Edit): id and action, DISABLE or ENABLE. A disabled link shows visitors the domain's disabled page, and keeps its history.
  • get_qr_style (Links · View): the colours, shape, margin and logo a link's QR code is drawn with, by id.
  • set_qr_style (Links · Edit): styles a link's QR code, checked for contrast. Takes id, fg and bg (colours as #rrggbb), transparent, shape (square, rounded or dot), margin and logo (your organisation's QR logo, uploaded in the console). plain: true makes it plain again. Styled codes depend on your plan.

What create_link and update_link take

  • Destination: url, a public http(s) address.
  • Address (create only): domain (one from list_domains; your own verified domain when left out, else the shared default), slug for a chosen back-half, path, and generate (random, sequential or shuffled) for a generated one.
  • Tags: tags, as "CAMPAIGN:autumn" tokens, at most 10.
  • When it works: liveOn, expires (ISO 8601) and maxClicks.
  • Protection: password.
  • UTM: utm_source, utm_medium, utm_campaign, utm_term and utm_content, added to the destination.
  • Preview: ogTitle, ogDescription and ogImage.
  • Event tracking (create only): trackConversions: true, for event tracking by link.
  • Safe retries: idempotency_key, below.

A field the tools don't know is refused by name, never ignored, so a misspelt field can't pass silently.

This is the call an assistant makes when you ask for a link. You can send it yourself:

bash
curl -X POST "$API/mcp" \  -H "x-api-key: $KEY" \  -H "x-api-secret: $SECRET" \  -H "content-type: application/json" \  -d '{"jsonrpc": "2.0", "id": 3, "method": "tools/call",       "params": {"name": "create_link",                  "arguments": {"url": "https://www.example.com/offers/winter",                                "slug": "winter",                                "utm_campaign": "winter",                                "idempotency_key": "6b1f0c4e-2a7d-4e59-9c3b-8d0a5e7f1b26"}}}'

The answer, trimmed: the link as the API returns it, in structuredContent, and the same as text in content.

json
{  "jsonrpc": "2.0",  "id": 3,  "result": {    "content": [{ "type": "text", "text": "{ … }" }],    "structuredContent": {      "id": "01M75QDW3502KJT2BKJ8KXV9FN",      "domain": "go.example.com",      "slug": "winter",      "shortUrl": "https://go.example.com/winter",      "destination": "https://www.example.com/offers/winter",      "opens": "https://www.example.com/offers/winter?utm_campaign=winter",      "status": "ACTIVE",      "…": "…"    }  }}

When a tool refuses

A refusal is the tool's answer, not a protocol error, so the assistant can read it and try again. It comes back with "isError": true and the reason in content, each refused field on its own line. A key that can't make tags, for example, sending a tag that doesn't exist yet, gets tags: You may pick existing tags only. A missing permission names the one the tool needs.

Safe retries with idempotency_key

An assistant that lost an answer may call again. create_link and update_link take an optional idempotency_key: any unique value of yours, such as a UUID, up to 255 characters.

  • The same value and the same arguments within 24 hours answer the first call's result, marked "_meta": {"replayed": true}, and make no second link or change.
  • The same value with other arguments is refused, naming idempotency_key. Use a new value for a new call.
  • While the first call is still running, a second is refused as still running. Try again in a moment.
  • A refusal isn't kept, so a call refused for a field can be sent again, corrected, with the same value.
  • A value belongs to its key and its tool.

The Idempotency-Key header the rest of the API takes doesn't apply to /api/mcp; this argument does the same job by the same rules. More on retries in API errors.

Common questions

Can an AI assistant delete my links through Brevily's MCP server?

No: there's no delete tool. With Links · Edit, an assistant can disable a link, which keeps its history and is undone with set_link_status.

Can any MCP client connect to Brevily's MCP server?

Any client that can send the key's two headers to /api/mcp over HTTP. The server has no OAuth sign-in yet, so a client that can only sign in through OAuth, or only speaks stdio, can't connect.

Do Brevily MCP calls count against the API rate limits?

Yes. MCP calls count against your organisation's per-minute and per-day API limits, shared by every key. The limits depend on your plan; see pricing.

Are short links made through the MCP server checked for safety?

Yes, exactly like links made in the console: create_link runs the same create, with the same destination checks.

Next steps

All developer guides

Brevily is invite-only, for now

Say what you would use it for and a person replies. Already invited? Sign in.