MCP URL Shortener
Let AI agents create and manage short links through MCP
Connect one remote Streamable HTTP endpoint, call shorten_url without a signup for the first task, and add account tools when the workflow needs aliases, tags, domains, or analytics.
By MiniURL · Updated
Why use an MCP URL shortener?
A normal URL shortener expects a person to open a web form or a developer to write API code. An MCP server gives an agent a typed tool list instead. The client can discover each tool, inspect its input schema, call it, and read a structured result while the user stays in the same conversation or automation run.
MiniURL's remote server uses Streamable HTTP, so supported clients connect to the hosted endpoint rather than installing a local package. The server is published as io.github.addychang/miniurl in the official MCP Registry, and its public documentation describes the same endpoint, session behavior, and tool names exposed by the live service.
Connect an MCP client in three steps
- Add the remote endpointConfigure the client with https://workers.miniurl.com/mcp using Streamable HTTP. Codex CLI, Claude Code, Gemini CLI, and other remote-MCP clients can connect without a local server process.
- Inspect the available toolsLet the client complete MCP initialization and tools/list. This exposes the current schemas for shortening, account access, link management, analytics, domains, and tags.
- Call shorten_urlPass the final HTTPS destination. Read the returned short URL and meta object, then show the link and any quota, expiry, or next-step notice to the user.
Match the task to the MCP tool
Start with the smallest tool that completes the user's request. Ask for account authentication only when the task needs saved-account features.
| Agent task | MiniURL tool | Access |
|---|---|---|
| Create one short link | shorten_url | Guest or registered |
| Check a readable path before launch | check_alias | Guest or registered |
| Create 1–10 Free or 1–50 Pro links | bulk_create_links | Registered |
| Find or update an existing link | list_links, get_link, update_link | Registered |
| Review click performance | get_link_stats | Registered |
| Organize campaign links | list_tags, create_tag, tag_link | Registered |
| Use a branded hostname | list_domains | Registered |
Move from a guest task to a managed workflow
Guest access is designed for a quick first result. The guest token is temporary and guest-created links have plan-specific limits and expiry behavior, so an agent should not promise permanent storage or advanced analytics without checking the response meta object.
When the user wants a permanent account, the agent can call send_registration_code and verify_registration_code. Verification completes the human account bootstrap but never returns a long-lived API key over MCP; the Agent must then connect through OAuth 2.1 + PKCE. clear_authentication removes the current session credential when the account context should be discarded.
Production checklist for agent-created links
A short link is a public redirect, so the agent should verify intent and preserve enough context for the user to review the result.
- Confirm the destinationUse the URL the user supplied, keep its required query parameters, and do not silently replace it with a guessed landing page.
- Check aliases before creationCall check_alias before requesting a custom alias, especially when the link will be printed or shared in a scheduled campaign.
- Return notices with the linkSurface expiry, quota, authentication, and upgrade information from the response meta object instead of showing only the short URL.
- Keep credentials out of chat outputTreat gt_, at_, and mk_ values as credentials. MCP production Agent access uses OAuth 2.1 + PKCE; never send a long-lived mk_ key through MCP or place credentials inside a public short URL.
Choose MCP or the REST API
Use MCP when the calling environment already understands tool discovery and session-based agent workflows. It reduces integration code and gives the model explicit tool descriptions for common operations. Use the REST API when a backend service needs direct HTTP control, fixed request handling, or an environment without MCP support.
Both interfaces reach the same MiniURL product capabilities, but their names and session rules differ. MCP clients should follow the tool schemas returned by tools/list. REST integrations should follow the OpenAPI document and API endpoint reference rather than translating MCP tool calls by guesswork.
MCP URL shortener FAQ
Does the MiniURL MCP server require a local installation?
No. MiniURL is a remote Streamable HTTP MCP server at https://workers.miniurl.com/mcp. A compatible client connects to that URL, completes MCP initialization, and discovers the live tool schemas.
Can an agent shorten a URL before the user signs up?
Yes. Calling shorten_url without stored authentication automatically opens a temporary guest session. The agent should read and relay the response meta object because it describes guest limits, expiry, and relevant next steps.
Is MiniURL listed in the official MCP Registry?
Yes. The official Registry name is io.github.addychang/miniurl, and its remote entry points to https://workers.miniurl.com/mcp using Streamable HTTP.
What if an agent client does not support MCP?
Use the MiniURL REST API instead. The public API documentation and OpenAPI file cover guest tokens, shortening, account conversion, aliases, links, analytics, domains, tags, and upgrade flows.
Build short links into your workflow
Use the REST API or MCP server when you need agents, scripts, or backend jobs to create and manage links.
Read API docs