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
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.
How Brevily's link shortener MCP server works
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/mcpon 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
POSTcarries one JSON-RPC 2.0 message and gets one answer. There's no session id and no event stream; aGETanswers 405. - Credential: the key's ID in
x-api-keyand its secret inx-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-26and2024-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
- 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.
- Give it a Label after the tool, such as "Claude Code, laptop", so you know what to revoke later.
- Under Permissions, give Links with View and Create. Add Edit if the assistant may change or disable links, or style their QR codes.
- 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:
API=https://console.brevily.com/apiKEY=brv_ak_… # the key's IDSECRET=… # its secretThe 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:
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:
{ "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.
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"}}}'{ "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:
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. Takesdomain(blank for the default),slugandpath.create_link(Links · Create): makes a link and answers its id and short URL. Onlyurlis required; the arguments are below.get_link(Links · View): one link byid, 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. Takesquery,state(ACTIVE,SCHEDULED,EXPIRED,DISABLEDorFLAGGED),domain,pathandpage.update_link(Links · Edit): changes a link byid. A field left out keeps its value, an empty string clears it (excepturl), andclearPassword: trueremoves the password. The domain, back-half and path never change.set_link_status(Links · Edit):idandaction,DISABLEorENABLE. 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, byid.set_qr_style(Links · Edit): styles a link's QR code, checked for contrast. Takesid,fgandbg(colours as#rrggbb),transparent,shape(square,roundedordot),marginandlogo(your organisation's QR logo, uploaded in the console).plain: truemakes 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 fromlist_domains; your own verified domain when left out, else the shared default),slugfor a chosen back-half,path, andgenerate(random,sequentialorshuffled) for a generated one. - Tags:
tags, as"CAMPAIGN:autumn"tokens, at most 10. - When it works:
liveOn,expires(ISO 8601) andmaxClicks. - Protection:
password. - UTM:
utm_source,utm_medium,utm_campaign,utm_termandutm_content, added to the destination. - Preview:
ogTitle,ogDescriptionandogImage. - 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.
Create a short link through the MCP server
This is the call an assistant makes when you ask for a link. You can send it yourself:
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.
{ "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
- Brevily API: everything the tools don't cover, such as routing rules and deleting links.
- Sign an API request: make the key the assistant connects with.
- Team roles and permissions: what a personal key's person may do decides what the assistant may do.
- Link safety: the checks every link the assistant makes goes through.
On this page