Pro and above. Developer reference. For the short version, see Use URLCrop in Claude, ChatGPT and Cursor.
URLCrop runs a remote Model Context Protocol (MCP) server so an MCP-capable app can create short links and QR codes in your workspace.
- Endpoint:
https://mcp.urlcrop.com/mcp - Transport: Streamable HTTP, stateless. Every
POSTgets a JSON response; there are no sessions and no server-sent event stream.GETandDELETEreturn405. - Protocol versions:
2025-11-25,2025-06-18and2025-03-26. If the client asks for another version, the server answers with2025-11-25. An unsupportedMCP-Protocol-Versionheader is rejected. - Plan: Pro and above.
- Who it acts as: you, in the one workspace you choose on the consent screen, with your own role in that workspace.
- What it can do: create only. It cannot read, edit or delete anything.
Set up your app
Menu names change between app versions; if you cannot find an item, search the app's settings for "connector" or "MCP".
| App | Steps |
|---|---|
| Claude (web and desktop) | Settings → Connectors → Add custom connector, paste https://mcp.urlcrop.com/mcp, then Connect and sign in to URLCrop. |
| ChatGPT | Turn on developer mode, then add a custom connector under Settings → Apps & Connectors with the same address. Custom connectors depend on your ChatGPT plan, so they may not be available on every account. |
| Cursor | Add the server to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project). |
| VS Code | Add the server to .vscode/mcp.json. |
| Other clients | Any client that supports remote MCP over HTTP with OAuth works. Give it the endpoint above. |
Cursor:
{ "mcpServers": { "urlcrop": { "url": "https://mcp.urlcrop.com/mcp" } } }VS Code:
{ "servers": { "urlcrop": { "type": "http", "url": "https://mcp.urlcrop.com/mcp" } } }No API key is needed. The first time the app connects, it opens a URLCrop sign-in and consent page.
Authorization
The server uses OAuth 2.1 (authorization code flow) with PKCE. Only the S256 challenge method is accepted.
- Discovery:
https://mcp.urlcrop.com/.well-known/oauth-protected-resourceandhttps://mcp.urlcrop.com/.well-known/oauth-authorization-server. A request without a valid token gets401with aWWW-Authenticateheader that points to the first one. - Registration: apps register themselves with dynamic client registration (
POST /oauth/register, up to 5 redirect URIs). You do not create a client in URLCrop. - Resource: the app must send the
resourceparameterhttps://mcp.urlcrop.com/mcpwhen it asks for authorization and for a token. A token issued for the connector works only on/mcp, never on the public API. - Scopes:
links:write(lets the app usecreate_short_link) andqr:write(lets the app usecreate_qr_code). If the app does not ask for scopes, it gets both. - Consent screen: you must be signed in with a verified email, and the sign-in must be recent (within 10 minutes). The screen shows the app name, where it will redirect and the workspace. Apps URLCrop does not know are marked Unverified app. Owners and Admins on Business and above may be asked for their two-step code.
- Tokens: access tokens last 1 hour. Refresh tokens last 30 days and rotate on every use, with a 90-day cap from the first approval, after which the app asks you to connect again. Reusing an old refresh token revokes the connection.
- Revoking: Account → Connected apps → Revoke. Access stops at once. It also stops when you reset your password, leave the workspace, lose the role needed to create links, or the workspace is suspended or deleted.
Tools
Both tools appear in tools/list only if the connection holds the matching scope.
create_short_link (scope links:write)
| Field | Type | Required | Notes |
|---|---|---|---|
url | string, 1 to 2048 characters | Yes | Destination, a public http or https address. |
slug | string, 1 to 64 characters | No | Custom back-half. Needs Starter and above; reserved and taken words are refused. |
title | string, 1 to 200 characters | No | Label shown in the dashboard. |
idempotency_key | string, 1 to 128 characters | No | See "Repeated calls" below. |
Result fields: id, short_url, destination, safety_status and dashboard_url. The result also comes back as a one-line text message.
create_qr_code (scope qr:write)
| Field | Type | Required | Notes |
|---|---|---|---|
url | string, 1 to 2048 characters | Yes | Destination, a public http or https address. |
label | string, 1 to 120 characters | No | Name of the QR code in the dashboard. |
idempotency_key | string, 1 to 128 characters | No | See "Repeated calls" below. |
The QR code is dynamic (you can change its destination later in the dashboard). Result fields: id, short_url, png_url and svg_url.
Short link domain. The host in short_url follows the workspace's Short link domain setting, go.crop.sh or crop.sh.
Example tools/call request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "create_short_link",
"arguments": { "url": "https://example.com/sale", "slug": "sale" }
}
}Limits and errors
- Request size: a request body is at most 64 KB.
- Daily quota: each
tools/callcounts as one request toward your plan's daily API request limit, and the plan's burst limit applies. Other calls, such asinitializeandtools/list, do not use the daily quota. - Per connection: up to 10 non-tool calls per second and 50 tool calls per second for each connection. Beyond that the server answers
429. - Repeated calls: a call with the same tool and the same arguments from the same connection within the same 10-minute window returns the original link or QR code instead of creating a duplicate. Send your own
idempotency_keyto control this; a key replaces the time window. - Everything else that limits the dashboard also limits the tools: links per month, QR codes, role and email verification.
A failed tool call returns a normal result with isError: true and one of these messages:
| Message | Cause |
|---|---|
| "The MCP connector needs a Pro plan or above, and this workspace is not on one." | The workspace is on Free or Starter. |
| "This workspace has reached its plan limit for this action." | Links per month or QR codes used up. |
| "That custom back-half is reserved / already in use / not valid." | The slug is a reserved word, taken, or uses characters other than letters, numbers, hyphens and underscores. |
| "URLCrop's link safety blocked this destination, so nothing was created." | The destination scored as blocked by link safety. |
| "That destination URL is not allowed. Use a public http or https address." | The URL is private, malformed or uses another scheme. |
| "That destination could not be reached, so nothing was created." | The destination did not answer. |
| "Your role in this workspace does not allow creating this." | You are a Viewer, or lack the role the action needs. Ask a workspace admin. |
| "This connection was not granted permission for that action." | The app was connected without the matching scope. Reconnect and approve both. |
| "Verify your email address in URLCrop before creating anything." | Your email is not verified. |
| "This workspace is read-only until its payment is up to date." | The workspace is past due. Existing links keep working. |
| "This workspace is suspended, so nothing can be created." | The workspace is suspended. |
| "This action needs approval from a workspace admin before it takes effect." | Approvals are on and the request was queued. |
| "This workspace has used its daily API request quota." | The daily limit is reached; the message may include a wait time. |
| "Too many requests right now." | The plan's burst limit was hit; retry after the time shown. |
| "URLCrop could not complete this request. Try again later." | A server-side error. |
Other errors use the usual API error text. Server errors never include internal details.
Security notes
- Create only. The connector has no read, edit or delete tools, and no scope that would allow them.
- Same safety checks. Links and QR codes go through the same link safety checks, plan limits and approval rules as the dashboard. Unknown destinations are not treated as safe automatically.
- Your role applies. Your current role in the workspace is checked on every call, as well as the scopes.
- Tokens stay private. Never put a token in a URL; a token in a query string is rejected. URLCrop stores tokens only as hashes.
- Revoke any time under Account → Connected apps. Approve only apps you started connecting yourself.
Questions? Email support@urlcrop.com with the app name and the time of the attempt.