Tools Reference

Authentication

MCP requests are authenticated using the same API keys as the REST API. Pass your key in the Authorization header of the MCP connection.

Tool	Required scope
`create_short_link`	`write`
`bulk_create_links`	`write`
`list_links`	`read`
`get_analytics`	`read`
`revoke_link`	`write`
`generate_qr`	`read`

An API key with read + write scopes covers all tools.

create_short_link

Create a new shortened link.

Parameters

Name	Type	Required	Description
`url`	string	Yes	Destination URL to shorten
`custom_slug`	string	No	Custom slug (auto-generated if omitted)
`tags`	string[]	No	Tags for organization (max 3, each ≤ 50 chars)
`include_qr`	boolean	No	Include QR code SVG in response

Example prompt

"Shorten this URL: https://docs.example.com/api/v2/getting-started"

Response

{
  "short_url": "https://r.shorten.dev/x7kQ2m",
  "link": {
    "slug": "x7kQ2m",
    "destination_url": "https://docs.example.com/api/v2/getting-started",
    "status": "active",
    "threat_type": null,
    "revoked_at": null,
    "tags": [],
    "created_at": "2026-02-15T12:00:00Z",
    "updated_at": "2026-02-15T12:00:00Z"
  }
}

bulk_create_links

Create multiple shortened links in a single request (max 500). The operation is all-or-nothing.

Parameters

Name	Type	Required	Description
`links`	array	Yes	Array of link objects (1–500)
`links[].url`	string	Yes	Destination URL to shorten
`links[].custom_slug`	string	No	Custom slug (auto-generated if omitted)
`links[].tags`	string[]	No	Tags for organization (max 3, each ≤ 50 chars)

Example prompt

"Create short links for these three docs pages: https://docs.example.com/guide-1, https://docs.example.com/guide-2, https://docs.example.com/guide-3"

Response

{
  "links": [
    {
      "link": {
        "slug": "aB3nP9k",
        "destination_url": "https://docs.example.com/guide-1",
        "status": "active",
        "threat_type": null,
        "revoked_at": null,
        "tags": [],
        "created_at": "2026-02-23T00:00:00Z",
        "updated_at": "2026-02-23T00:00:00Z"
      },
      "short_url": "https://r.shorten.dev/aB3nP9k"
    }
  ],
  "total_created": 3
}

list_links

List all links for the authenticated user with optional filtering.

Parameters

Name	Type	Required	Description
`limit`	integer	No	Maximum results (default: 10, max: 50)
`status`	string	No	Filter: `active`, `flagged`, or `revoked`
`search`	string	No	Search in slug and destination URL

Example prompt

"Show me my 5 most recent active links"

Response

{
  "links": [
    {
      "slug": "x7kQ2m",
      "destination_url": "https://docs.example.com/tutorials",
      "status": "active",
      "threat_type": null,
      "revoked_at": null,
      "tags": ["marketing"],
      "created_at": "2026-02-15T12:00:00Z",
      "updated_at": "2026-02-15T12:00:00Z"
    }
  ],
  "total": 25
}

get_analytics

Retrieve click analytics for a specific link.

Parameters

Name	Type	Required	Description
`slug`	string	Yes	The link slug
`period`	string	No	`7d`, `30d`, or `90d` (default: `7d`)

Example prompt

"How many clicks did r.shorten.dev/x7kQ2m get this month?"

Response

{
  "slug": "x7kQ2m",
  "period": "30d",
  "total_clicks": 12847,
  "unique_visitors": 8234,
  "time_series": [
    { "date": "2026-01-17", "clicks": 423 },
    { "date": "2026-01-18", "clicks": 512 }
  ],
  "top_referrers": [
    { "referrer": "google.com", "count": 4521 },
    { "referrer": "twitter.com", "count": 2103 }
  ],
  "top_countries": [
    { "country": "US", "count": 5423 },
    { "country": "GB", "count": 1876 }
  ],
  "top_devices": [
    { "device": "desktop", "count": 7981 },
    { "device": "mobile", "count": 3989 }
  ],
  "top_browsers": [
    { "browser": "Chrome", "count": 7234 },
    { "browser": "Safari", "count": 2876 }
  ]
}

revoke_link

Permanently revoke a shortened link. The short URL will stop redirecting immediately. This cannot be undone.

Parameters

Name	Type	Required	Description
`slug`	string	Yes	The link slug to revoke

Example prompt

"Revoke the link r.shorten.dev/x7kQ2m — it's no longer needed"

Response

{
  "slug": "x7kQ2m",
  "destination_url": "https://docs.example.com/api/v2/getting-started",
  "status": "revoked",
  "threat_type": null,
  "revoked_at": "2026-02-23T18:30:00Z",
  "tags": [],
  "created_at": "2026-02-15T12:00:00Z",
  "updated_at": "2026-02-23T18:30:00Z"
}

generate_qr

Generate a QR code for an existing shortened link.

Parameters

Name	Type	Required	Description
`slug`	string	Yes	The link slug to generate a QR code for
`format`	string	No	Output format: `svg` (default) or `png_data_url`

Example prompt

"Generate a QR code for r.shorten.dev/x7kQ2m"

Response

{
  "slug": "x7kQ2m",
  "short_url": "https://r.shorten.dev/x7kQ2m",
  "format": "svg",
  "qr_code": "<svg xmlns=\"http://www.w3.org/2000/svg\" ...>...</svg>"
}

Authentication

MCP requests are authenticated using the same API keys as the REST API. Pass your key in the Authorization header of the MCP connection.

Tool	Required scope
`create_short_link`	`write`
`bulk_create_links`	`write`
`list_links`	`read`
`get_analytics`	`read`
`revoke_link`	`write`
`generate_qr`	`read`

An API key with read + write scopes covers all tools.

create_short_link

Create a new shortened link.

Parameters

Name	Type	Required	Description
`url`	string	Yes	Destination URL to shorten
`custom_slug`	string	No	Custom slug (auto-generated if omitted)
`tags`	string[]	No	Tags for organization (max 3, each ≤ 50 chars)
`include_qr`	boolean	No	Include QR code SVG in response

Example prompt

"Shorten this URL: https://docs.example.com/api/v2/getting-started"

Response

{
  "short_url": "https://r.shorten.dev/x7kQ2m",
  "link": {
    "slug": "x7kQ2m",
    "destination_url": "https://docs.example.com/api/v2/getting-started",
    "status": "active",
    "threat_type": null,
    "revoked_at": null,
    "tags": [],
    "created_at": "2026-02-15T12:00:00Z",
    "updated_at": "2026-02-15T12:00:00Z"
  }
}

bulk_create_links

Create multiple shortened links in a single request (max 500). The operation is all-or-nothing.

Parameters

Name	Type	Required	Description
`links`	array	Yes	Array of link objects (1–500)
`links[].url`	string	Yes	Destination URL to shorten
`links[].custom_slug`	string	No	Custom slug (auto-generated if omitted)
`links[].tags`	string[]	No	Tags for organization (max 3, each ≤ 50 chars)

Example prompt

"Create short links for these three docs pages: https://docs.example.com/guide-1, https://docs.example.com/guide-2, https://docs.example.com/guide-3"

Response

{
  "links": [
    {
      "link": {
        "slug": "aB3nP9k",
        "destination_url": "https://docs.example.com/guide-1",
        "status": "active",
        "threat_type": null,
        "revoked_at": null,
        "tags": [],
        "created_at": "2026-02-23T00:00:00Z",
        "updated_at": "2026-02-23T00:00:00Z"
      },
      "short_url": "https://r.shorten.dev/aB3nP9k"
    }
  ],
  "total_created": 3
}

list_links

List all links for the authenticated user with optional filtering.

Parameters

Name	Type	Required	Description
`limit`	integer	No	Maximum results (default: 10, max: 50)
`status`	string	No	Filter: `active`, `flagged`, or `revoked`
`search`	string	No	Search in slug and destination URL

Example prompt

"Show me my 5 most recent active links"

Response

{
  "links": [
    {
      "slug": "x7kQ2m",
      "destination_url": "https://docs.example.com/tutorials",
      "status": "active",
      "threat_type": null,
      "revoked_at": null,
      "tags": ["marketing"],
      "created_at": "2026-02-15T12:00:00Z",
      "updated_at": "2026-02-15T12:00:00Z"
    }
  ],
  "total": 25
}

get_analytics

Retrieve click analytics for a specific link.

Parameters

Name	Type	Required	Description
`slug`	string	Yes	The link slug
`period`	string	No	`7d`, `30d`, or `90d` (default: `7d`)

Example prompt

"How many clicks did r.shorten.dev/x7kQ2m get this month?"

Response

{
  "slug": "x7kQ2m",
  "period": "30d",
  "total_clicks": 12847,
  "unique_visitors": 8234,
  "time_series": [
    { "date": "2026-01-17", "clicks": 423 },
    { "date": "2026-01-18", "clicks": 512 }
  ],
  "top_referrers": [
    { "referrer": "google.com", "count": 4521 },
    { "referrer": "twitter.com", "count": 2103 }
  ],
  "top_countries": [
    { "country": "US", "count": 5423 },
    { "country": "GB", "count": 1876 }
  ],
  "top_devices": [
    { "device": "desktop", "count": 7981 },
    { "device": "mobile", "count": 3989 }
  ],
  "top_browsers": [
    { "browser": "Chrome", "count": 7234 },
    { "browser": "Safari", "count": 2876 }
  ]
}

revoke_link

Permanently revoke a shortened link. The short URL will stop redirecting immediately. This cannot be undone.

Parameters

Name	Type	Required	Description
`slug`	string	Yes	The link slug to revoke

Example prompt

"Revoke the link r.shorten.dev/x7kQ2m — it's no longer needed"

Response

{
  "slug": "x7kQ2m",
  "destination_url": "https://docs.example.com/api/v2/getting-started",
  "status": "revoked",
  "threat_type": null,
  "revoked_at": "2026-02-23T18:30:00Z",
  "tags": [],
  "created_at": "2026-02-15T12:00:00Z",
  "updated_at": "2026-02-23T18:30:00Z"
}

generate_qr

Generate a QR code for an existing shortened link.

Parameters

Name	Type	Required	Description
`slug`	string	Yes	The link slug to generate a QR code for
`format`	string	No	Output format: `svg` (default) or `png_data_url`

Example prompt

"Generate a QR code for r.shorten.dev/x7kQ2m"

Response

{
  "slug": "x7kQ2m",
  "short_url": "https://r.shorten.dev/x7kQ2m",
  "format": "svg",
  "qr_code": "<svg xmlns=\"http://www.w3.org/2000/svg\" ...>...</svg>"
}

Tools Reference

Authentication

create_short_link

bulk_create_links

list_links

get_analytics

revoke_link

generate_qr

On this page

Tools Reference

Authentication

create_short_link

bulk_create_links

list_links

get_analytics

revoke_link

generate_qr

On this page