Long links are a tiny annoyance until they show up everywhere: PR descriptions, commit messages, README files, release notes, Slack threads, and internal docs. The practical goal of this guide is simple: let Claude Code shorten links from the terminal while you are already working on the surrounding text.
ShortURL MCP is a small but useful example of what Model Context Protocol tools are good at. It does not try to replace your editor or your coding agent. It gives Claude Code one focused capability: turn long links into cleaner https://surl.id/xxxxx links, including batch workflows for multiple URLs.
What you can do
After connecting the ShortURL MCP server, Claude Code can call link-shortening tools from a normal terminal session. The source document describes several everyday scenarios:
- shortening an issue or document link before putting it into a commit message;
- replacing multiple long external links in a README;
- preparing friendlier links before sending them to non-technical teammates;
- asking Claude Code to handle the link cleanup while it is already editing nearby Markdown.
The MCP server exposes these tools:
| Tool | Purpose |
|---|---|
shorturl_create |
Generate one short link |
shorturl_batch_create |
Generate multiple short links at once |
shorturl_get_api_info |
Get API information |
shorturl_get_usage_guide |
Get the usage guide |
The important thing is not the short link itself. It is the workflow placement. If Claude Code is already drafting a PR description or editing a README, link shortening becomes one more tool call instead of a browser detour.
How it works
ShortURL is exposed as a remote MCP server. Claude Code connects to it over HTTP, and your Ace Data Cloud API token is provided through the Authorization header.
The setup fields from the documentation are:
- MCP server URL:
https://shorturl.mcp.acedata.cloud/mcp - Transport:
http - Authorization header:
Authorization: Bearer YOUR_ACEDATACLOUD_API_KEY - Claude Code command:
claude mcp add - Verification command:
claude mcp list - Expected server name after setup:
shorturl
The documentation shows three configuration scopes: local, user, and project. Use local for a single project, user if you want the server available across projects, and project if a private team repository should carry the MCP configuration.
Configure it locally first
For a first run, I prefer the local scope. It keeps the setup attached to the current project directory and avoids changing your global Claude Code configuration.
claude mcp add shorturl --transport http https://shorturl.mcp.acedata.cloud/mcp \
-H "Authorization: Bearer YOUR_ACEDATACLOUD_API_KEY" \
-s local
Two details are easy to miss:
-
-Hmust be uppercase. Lowercase-hmeans--help. - Keep the full header format:
Authorization: Bearer ....
After adding the server, verify that Claude Code can see it:
claude mcp list
If shorturl shows ✓ Connected, the MCP handshake worked. If it does not, check the token, the server URL, and the scope before changing anything else.
Use it in a PR or commit workflow
Imagine you are writing a commit message that references a long issue URL. Instead of manually opening a URL shortener, ask Claude Code directly:
Shorten this issue link; I want to put it in the commit message.
Claude Code can then call shorturl_create and return a compact link in the https://surl.id/xxxxx format described by the docs. The result is easier to scan in terminal output, commit bodies, chat messages, and changelog drafts.
This is a good fit for links that are useful but noisy: GitHub issue filters, permanent line references, documentation pages with tracking parameters, or internal tools that generate very long URLs.
Batch-clean links in Markdown
The more interesting workflow is batch cleanup. The docs describe shorturl_batch_create for shortening multiple links at once. That maps naturally to README and release-note maintenance.
A useful prompt is:
Help me replace all long external links in the README with short links.
In a real project, I would make that instruction more constrained:
Find external links in README.md that are longer than 100 characters. Use shorturl_batch_create to shorten them, then update the Markdown while keeping the link text unchanged.
That keeps the content readable while reducing link noise. It also gives Claude Code a clear editing rule: change the URL target, not the surrounding prose.
Choose the right scope
Use local when you are testing or when only one repository needs short links.
Use user when shortening links is part of your personal writing workflow across projects. The documentation notes that user-level configuration is written into the local ~/.claude.json, so projects opened later can see it.
Use project for team workflows, but be careful with secrets. The documentation says project-level configuration is written into .mcp.json in the project root. That can be useful in a private repository, but the real token should not be committed to a public repo. The first time Claude Code reads project-level configuration, it may show Pending approval; you need to trust that configuration inside the session.
Final notes
ShortURL MCP is intentionally small, which is why it is a good first MCP workflow to try in Claude Code. It has a clear input, a clear output, and a practical place in daily engineering writing. Start with local, verify with claude mcp list, and then use shorturl_create or shorturl_batch_create only where shorter links make the surrounding text easier to read.
The original Ace Data Cloud setup reference is here: Claude Code with ShortURL MCP.
Top comments (1)
The README example gives
shorturl_batch_createa clear boundary: external URLs over 100 characters, with the link text left intact. I'd be careful applying the same cleanup to commit messages or long-lived docs, though. Asurl.idlink hides its destination and makes future readers depend on the redirect still working. For repository history, removing tracking parameters or using canonical URLs first often improves readability without adding that dependency.