Skip to content

URLCrop MCP server

Pro and above. Developer reference. For the short version, see Use URLCrop in Claude, ChatGPT and Cursor.

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 POST gets a JSON response; there are no sessions and no server-sent event stream. GET and DELETE return 405.
  • Protocol versions: 2025-11-25, 2025-06-18 and 2025-03-26. If the client asks for another version, the server answers with 2025-11-25. An unsupported MCP-Protocol-Version header 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".

AppSteps
Claude (web and desktop)Settings → Connectors → Add custom connector, paste https://mcp.urlcrop.com/mcp, then Connect and sign in to URLCrop.
ChatGPTTurn 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.
CursorAdd the server to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project).
VS CodeAdd the server to .vscode/mcp.json.
Other clientsAny 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-resource and https://mcp.urlcrop.com/.well-known/oauth-authorization-server. A request without a valid token gets 401 with a WWW-Authenticate header 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 resource parameter https://mcp.urlcrop.com/mcp when 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 use create_short_link) and qr:write (lets the app use create_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)

FieldTypeRequiredNotes
urlstring, 1 to 2048 charactersYesDestination, a public http or https address.
slugstring, 1 to 64 charactersNoCustom back-half. Needs Starter and above; reserved and taken words are refused.
titlestring, 1 to 200 charactersNoLabel shown in the dashboard.
idempotency_keystring, 1 to 128 charactersNoSee "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)

FieldTypeRequiredNotes
urlstring, 1 to 2048 charactersYesDestination, a public http or https address.
labelstring, 1 to 120 charactersNoName of the QR code in the dashboard.
idempotency_keystring, 1 to 128 charactersNoSee "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/call counts as one request toward your plan's daily API request limit, and the plan's burst limit applies. Other calls, such as initialize and tools/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_key to 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:

MessageCause
"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.