esyURL
Short links and trackable QR codes: editable after printing, device routing, scan stats.
Should I use this
Quality & Safety
Findings (2)
- HIGHTool poisoning patterns detected
- MEDIUMTool description contains URL to non-standard domainin set_custom_domain
Based on automated analysis of tool definitions and protocol compliance.
Context Cost
This is the approximate number of tokens consumed each time the server's tools are loaded into a model's context. Higher counts reduce the attention available for other tasks.
Install
One-Click Install
Add this to your `claude_desktop_config.json` file:
{
"mcpServers": {
"mcp": {
"url": "https://esyurl.fyi/mcp"
}
}
}Remote endpoints
https://esyurl.fyi/mcpstreamable-httpWhat it can do
Tool inventory
Tools (19)
🟡create_short_link(targetUrl, name, slug, tags, metadata, ...)
Create a short link that redirects to targetUrl. Returns the link, including linkId (use it with the other tools) and shortUrl (share this). Give a slug for a memorable URL, otherwise a random 8-character one is generated. Slugs are unique across all tenants and cannot be changed later (409 if taken; route names like "api", "admin", "health" are reserved).
Input Schema
{
"type": "object",
"properties": {
"targetUrl": {
"type": "string",
"description": "Absolute http(s) URL visitors are redirected to"
},
"name": {
"description": "Human label, up to 200 chars",
"type": "string"
},
"slug": {
"description": "Custom slug, ^[a-zA-Z0-9_-]{3,64}$; random if omitted",
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Free-form labels, up to 20; filter with list_short_links tag"
},
"metadata": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
},
"description": "Up to 20 string key/value pairs for your own bookkeeping"
},
"qrStyle": {
"type": "object",
"properties": {
"dark": {
"type": "string",
"description": "Hex colour, e.g. #000000 (the # is optional)"
},
"light": {
"type": "string",
"description": "Hex colour, e.g. #000000 (the # is optional)"
},
"errorCorrectionLevel": {
"type": "string",
"enum": [
"L",
"M",
"Q",
"H"
],
"description": "QR error correction level: L 7%, M 15% (default), Q 25%, H 30%"
},
"margin": {
"description": "Quiet zone in modules, 0-16",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"modules": {
"description": "Shape of the data modules (default square)",
"type": "string",
"enum": [
"square",
"rounded",
"dot",
"row",
"column"
]
},
"eyeFrame": {
"description": "Outer ring of the three corner markers",
"type": "string",
"enum": [
"square",
"rounded",
"circle"
]
},
"eyeBall": {
"description": "Centre of the corner markers",
"type": "string",
"enum": [
"square",
"rounded",
"circle"
]
},
"eyeColor": {
"description": "Colour of the corner markers; defaults to dark",
"type": "string"
},
"image": {
"description": "A picture in the code. mode \"logo\": in the middle (error correction becomes H; size is its side as a share of the code, 0.1-0.3, default 0.22). mode \"halftone\": a photo behind the code, drawn as dots over it. data is a data URL (data:image/png;base64,... png, jpeg, webp or gif, up to 2 MB). To keep the current picture while changing other fields, pass its imageId instead of data.",
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"logo",
"halftone"
]
},
"data": {
"description": "A new picture, as a data URL",
"type": "string"
},
"imageId": {
"description": "Keep the picture the link already has (its qrStyle.image.imageId)",
"type": "string"
},
"size": {
"type": "number"
}
},
"required": [
"mode"
]
}
},
"description": "Default look of this link's QR image (free): colours, module and corner-marker shapes, and an optional picture. Styled codes need dark on light with at least 3:1 contrast. The whole style is replaced on update."
},
"groupIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Ids of groups (from create_group/list_groups) this link belongs to, up to 20"
},
"rules": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"description": "Stable id, shown on visits; generated if omitted. Keep it when editing a rule",
"type": "string"
},
"name": {
"type": "string"
},
"enabled": {
"description": "Default true; false keeps the rule but skips it",
"type": "boolean"
},
"when": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {},
"description": "The condition, e.g. {\"field\":\"os\",\"op\":\"eq\",\"value\":\"ios\"}"
},
"targetUrl": {
"type": "string",
"description": "Absolute http(s) destination when this rule matches"
}
},
"required": [
"when",
"targetUrl"
]
},
"description": "Redirect rules, evaluated in order on every visit; the first enabled rule whose \"when\" matches sends the visitor to its targetUrl, otherwise the link's targetUrl is used. A condition is either a test {field, op, value} or a combination {all: [...]}, {any: [...]}, {not: {...}}. Fields and their ops: os (ios|android|windows|macos|linux|chromeos|other), device (mobile|tablet|desktop|bot), browser (safari|chrome|firefox|edge|samsung|opera|in_app|other), source (qr|direct|bot): eq, neq, in, not_in. language (Accept-Language primary tag; \"pt\" also matches \"pt-BR\"): eq, neq, in, not_in, exists. country (ISO 3166-1 alpha-2, e.g. \"GB\", geolocated by the edge on every host): eq, neq, in, not_in. An unknown or absent value fails eq/in and passes neq/not_in. referrer (host, e.g. instagram.com) and query (needs \"key\", the parameter name): eq, neq, in, not_in, contains, starts_with, ends_with, exists. time (ISO timestamp): before, after. weekday (sun..sat, UTC): eq, neq, in, not_in. hour (0-23 UTC): eq, neq, in, not_in, gte, lte. in/not_in take an array. Text compares case-insensitively. Up to 20 rules, 20 conditions per rule. Example app-store split: [{\"name\":\"iOS\",\"when\":{\"field\":\"os\",\"op\":\"eq\",\"value\":\"ios\"},\"targetUrl\":\"https://apps.apple.com/app/id123\"},{\"name\":\"Android\",\"when\":{\"field\":\"os\",\"op\":\"eq\",\"value\":\"android\"},\"targetUrl\":\"https://play.google.com/store/apps/details?id=com.example\"}]"
}
},
"required": [
"targetUrl"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢list_short_links(limit, cursor, tag, group)
List your short links, newest first. Filter by tag and/or groupId. A page can hold fewer than limit items even when more exist: keep calling with cursor = nextCursor until nextCursor is absent.
Input Schema
{
"type": "object",
"properties": {
"limit": {
"description": "Page size 1-100, default 20",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"cursor": {
"description": "nextCursor from the previous page; omit for the first page",
"type": "string"
},
"tag": {
"description": "Only links carrying this tag",
"type": "string"
},
"group": {
"description": "Only links in this group (groupId)",
"type": "string"
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢get_short_link(linkId)
Fetch one short link by linkId, including its groupIds and lifetime visitCount.
Input Schema
{
"type": "object",
"properties": {
"linkId": {
"type": "string",
"minLength": 1,
"description": "The link id (linkId), as returned by create_short_link or list_short_links"
}
},
"required": [
"linkId"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟡update_short_link(linkId, targetUrl, name, tags, metadata, ...)
Change a short link. Only the fields you pass change; tags, metadata, qrStyle and groupIds are replaced wholesale (pass the full new list; [] clears). Set targetUrl to send visitors somewhere else: the short URL and printed QR codes keep working. Set status "paused" to make the short URL answer 410, "active" to resume. The slug cannot be changed.
Input Schema
{
"type": "object",
"properties": {
"linkId": {
"type": "string",
"minLength": 1,
"description": "The link id (linkId), as returned by create_short_link or list_short_links"
},
"targetUrl": {
"description": "New absolute http(s) destination",
"type": "string"
},
"name": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Free-form labels, up to 20; filter with list_short_links tag"
},
"metadata": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
},
"description": "Up to 20 string key/value pairs for your own bookkeeping"
},
"qrStyle": {
"type": "object",
"properties": {
"dark": {
"type": "string",
"description": "Hex colour, e.g. #000000 (the # is optional)"
},
"light": {
"type": "string",
"description": "Hex colour, e.g. #000000 (the # is optional)"
},
"errorCorrectionLevel": {
"type": "string",
"enum": [
"L",
"M",
"Q",
"H"
],
"description": "QR error correction level: L 7%, M 15% (default), Q 25%, H 30%"
},
"margin": {
"description": "Quiet zone in modules, 0-16",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"modules": {
"description": "Shape of the data modules (default square)",
"type": "string",
"enum": [
"square",
"rounded",
"dot",
"row",
"column"
]
},
"eyeFrame": {
"description": "Outer ring of the three corner markers",
"type": "string",
"enum": [
"square",
"rounded",
"circle"
]
},
"eyeBall": {
"description": "Centre of the corner markers",
"type": "string",
"enum": [
"square",
"rounded",
"circle"
]
},
"eyeColor": {
"description": "Colour of the corner markers; defaults to dark",
"type": "string"
},
"image": {
"description": "A picture in the code. mode \"logo\": in the middle (error correction becomes H; size is its side as a share of the code, 0.1-0.3, default 0.22). mode \"halftone\": a photo behind the code, drawn as dots over it. data is a data URL (data:image/png;base64,... png, jpeg, webp or gif, up to 2 MB). To keep the current picture while changing other fields, pass its imageId instead of data.",
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"logo",
"halftone"
]
},
"data": {
"description": "A new picture, as a data URL",
"type": "string"
},
"imageId": {
"description": "Keep the picture the link already has (its qrStyle.image.imageId)",
"type": "string"
},
"size": {
"type": "number"
}
},
"required": [
"mode"
]
}
},
"description": "Default look of this link's QR image (free): colours, module and corner-marker shapes, and an optional picture. Styled codes need dark on light with at least 3:1 contrast. The whole style is replaced on update."
},
"status": {
"type": "string",
"enum": [
"active",
"paused"
]
},
"groupIds": {
"description": "The complete new set of groups; replaces the current one",
"type": "array",
"items": {
"type": "string"
}
},
"rules": {
"description": "The complete new rule list; replaces the current one ([] removes all). Redirect rules, evaluated in order on every visit; the first enabled rule whose \"when\" matches sends the visitor to its targetUrl, otherwise the link's targetUrl is used. A condition is either a test {field, op, value} or a combination {all: [...]}, {any: [...]}, {not: {...}}. Fields and their ops: os (ios|android|windows|macos|linux|chromeos|other), device (mobile|tablet|desktop|bot), browser (safari|chrome|firefox|edge|samsung|opera|in_app|other), source (qr|direct|bot): eq, neq, in, not_in. language (Accept-Language primary tag; \"pt\" also matches \"pt-BR\"): eq, neq, in, not_in, exists. country (ISO 3166-1 alpha-2, e.g. \"GB\", geolocated by the edge on every host): eq, neq, in, not_in. An unknown or absent value fails eq/in and passes neq/not_in. referrer (host, e.g. instagram.com) and query (needs \"key\", the parameter name): eq, neq, in, not_in, contains, starts_with, ends_with, exists. time (ISO timestamp): before, after. weekday (sun..sat, UTC): eq, neq, in, not_in. hour (0-23 UTC): eq, neq, in, not_in, gte, lte. in/not_in take an array. Text compares case-insensitively. Up to 20 rules, 20 conditions per rule. Example app-store split: [{\"name\":\"iOS\",\"when\":{\"field\":\"os\",\"op\":\"eq\",\"value\":\"ios\"},\"targetUrl\":\"https://apps.apple.com/app/id123\"},{\"name\":\"Android\",\"when\":{\"field\":\"os\",\"op\":\"eq\",\"value\":\"android\"},\"targetUrl\":\"https://play.google.com/store/apps/details?id=com.example\"}]",
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"description": "Stable id, shown on visits; generated if omitted. Keep it when editing a rule",
"type": "string"
},
"name": {
"type": "string"
},
"enabled": {
"description": "Default true; false keeps the rule but skips it",
"type": "boolean"
},
"when": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {},
"description": "The condition, e.g. {\"field\":\"os\",\"op\":\"eq\",\"value\":\"ios\"}"
},
"targetUrl": {
"type": "string",
"description": "Absolute http(s) destination when this rule matches"
}
},
"required": [
"when",
"targetUrl"
]
}
}
},
"required": [
"linkId"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🔴delete_short_link(linkId)
Permanently delete a short link and remove it from its groups. Its short URL and any printed QR codes stop working (404) and the slug becomes free for anyone. Prefer update_short_link status "paused" if the link may come back.
Input Schema
{
"type": "object",
"properties": {
"linkId": {
"type": "string",
"minLength": 1,
"description": "The link id (linkId), as returned by create_short_link or list_short_links"
}
},
"required": [
"linkId"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢test_redirect_rules(linkId, userAgent, acceptLanguage, referrer, country, ...)
Dry run: which destination would a visit with these properties get from this link's rules? Records no visit. Pass a real userAgent to test device routing, e.g. iPhone: "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1", Android: "Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0 Mobile Safari/537.36". Returns targetUrl, matchedRule (absent when the link's targetUrl is used) and the context the rules saw (os, device, browser, language, country, referrer, source, query, at).
Input Schema
{
"type": "object",
"properties": {
"linkId": {
"type": "string",
"minLength": 1,
"description": "The link id (linkId), as returned by create_short_link or list_short_links"
},
"userAgent": {
"type": "string"
},
"acceptLanguage": {
"description": "e.g. \"pt-BR,pt;q=0.9,en;q=0.8\"",
"type": "string"
},
"referrer": {
"description": "Full referring URL, e.g. https://www.instagram.com/",
"type": "string"
},
"country": {
"description": "ISO 3166-1 alpha-2 country the visitor is in, e.g. \"GB\"",
"type": "string"
},
"query": {
"description": "Query parameters on the short URL",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"source": {
"description": "qr simulates a scanned QR code; default direct",
"type": "string",
"enum": [
"qr",
"direct"
]
},
"at": {
"description": "ISO timestamp to evaluate time/weekday/hour rules at; default now",
"type": "string"
}
},
"required": [
"linkId"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢get_short_link_visits(linkId, days, recent)
Visit analytics for one link: totals over the window ({visits, qr, direct, bot}; visits = qr + direct, bots such as link-preview crawlers are counted separately and excluded from visits), a zero-filled per-day breakdown (UTC, oldest first), and the most recent individual visits (newest first, with source, referrerHost, userAgent, country when known, and ruleId when a redirect rule decided it; kept 90 days). byRule splits the window's visits by rule (fallback = went to the link's targetUrl); daily entries carry byRule on days a rule matched.
Input Schema
{
"type": "object",
"properties": {
"linkId": {
"type": "string",
"minLength": 1,
"description": "The link id (linkId), as returned by create_short_link or list_short_links"
},
"days": {
"description": "How many UTC days back, including today: 1-365, default 30",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"recent": {
"description": "How many recent visit events to include, 0-200, default 50",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"linkId"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢render_qr_code(linkId, data, size, margin, dark, ...)
Render a QR code as a PNG image. Pass linkId to render a short link: the image encodes {shortUrl}?s=qr so scans are counted as qr visits, and the link's qrStyle is the default look. Or pass data to render any text (URL, Wi-Fi config, vCard...) as a static QR code that is not tracked. Returns the image plus a text line naming exactly what was encoded. Styles are free: module shapes, corner markers, a logo or a halftone photo. For SVG, use GET /v1/links/{linkId}/qr?format=svg.
Input Schema
{
"type": "object",
"properties": {
"linkId": {
"description": "Render this short link (exclusive with data)",
"type": "string",
"minLength": 1
},
"data": {
"description": "Arbitrary text to encode, up to 2048 chars (exclusive with linkId)",
"type": "string"
},
"size": {
"description": "Width in pixels, 64-2048, default 512",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"margin": {
"description": "Quiet zone in modules, 0-16, default 4",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"dark": {
"type": "string",
"description": "Hex colour, e.g. #000000 (the # is optional)"
},
"light": {
"type": "string",
"description": "Hex colour, e.g. #000000 (the # is optional)"
},
"ecl": {
"type": "string",
"enum": [
"L",
"M",
"Q",
"H"
],
"description": "QR error correction level: L 7%, M 15% (default), Q 25%, H 30%"
},
"modules": {
"description": "Shape of the data modules (default square)",
"type": "string",
"enum": [
"square",
"rounded",
"dot",
"row",
"column"
]
},
"eyeFrame": {
"description": "Outer ring of the three corner markers",
"type": "string",
"enum": [
"square",
"rounded",
"circle"
]
},
"eyeBall": {
"description": "Centre of the corner markers",
"type": "string",
"enum": [
"square",
"rounded",
"circle"
]
},
"eyeColor": {
"description": "Colour of the corner markers; defaults to dark",
"type": "string"
},
"image": {
"description": "For data only (a link uses its saved qrStyle). A picture in the code. mode \"logo\": in the middle (error correction becomes H; size is its side as a share of the code, 0.1-0.3, default 0.22). mode \"halftone\": a photo behind the code, drawn as dots over it. data is a data URL (data:image/png;base64,... png, jpeg, webp or gif, up to 2 MB).",
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"logo",
"halftone"
]
},
"data": {
"type": "string"
},
"size": {
"type": "number"
}
},
"required": [
"mode",
"data"
]
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}🟡create_group(name, description, color)
Create a group to organise short links (e.g. a campaign or a venue). Groups are many-to-many: a link can be in up to 20 groups. Add links with add_links_to_group, or pass groupIds when creating/updating a link.
Input Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Group name, up to 100 chars"
},
"description": {
"description": "Up to 500 chars",
"type": "string"
},
"color": {
"description": "Hex colour for UIs, e.g. #3366ff",
"type": "string"
}
},
"required": [
"name"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢list_groups(limit, cursor)
List your groups (with linkCount), ordered by groupId. Page with cursor = nextCursor.
Input Schema
{
"type": "object",
"properties": {
"limit": {
"description": "Page size 1-100, default 20",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"cursor": {
"description": "nextCursor from the previous page; omit for the first page",
"type": "string"
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢get_group(groupId)
Fetch one group. To see its links use list_short_links with group = groupId.
Input Schema
{
"type": "object",
"properties": {
"groupId": {
"type": "string",
"minLength": 1,
"description": "The group id (groupId), as returned by create_group or list_groups"
}
},
"required": [
"groupId"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟡update_group(groupId, name, description, color)
Rename a group or change its description or color. Membership doesn't change here.
Input Schema
{
"type": "object",
"properties": {
"groupId": {
"type": "string",
"minLength": 1,
"description": "The group id (groupId), as returned by create_group or list_groups"
},
"name": {
"type": "string",
"description": "Group name, up to 100 chars"
},
"description": {
"description": "Up to 500 chars",
"type": "string"
},
"color": {
"description": "Hex colour for UIs, e.g. #3366ff",
"type": "string"
}
},
"required": [
"groupId"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🔴delete_group(groupId)
Delete a group. Its links are NOT deleted; they just stop being members.
Input Schema
{
"type": "object",
"properties": {
"groupId": {
"type": "string",
"minLength": 1,
"description": "The group id (groupId), as returned by create_group or list_groups"
}
},
"required": [
"groupId"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟡add_links_to_group(groupId, linkIds)
Add up to 25 links to a group in one call. Idempotent: links already in the group are reported in alreadyMembers rather than failing. Fails with not_found if any linkId is unknown (nothing is added).
Input Schema
{
"type": "object",
"properties": {
"groupId": {
"type": "string",
"minLength": 1,
"description": "The group id (groupId), as returned by create_group or list_groups"
},
"linkIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "1-25 linkIds"
}
},
"required": [
"groupId",
"linkIds"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🔴remove_link_from_group(groupId, linkId)
Take one link out of a group. The link itself is untouched.
Input Schema
{
"type": "object",
"properties": {
"groupId": {
"type": "string",
"minLength": 1,
"description": "The group id (groupId), as returned by create_group or list_groups"
},
"linkId": {
"type": "string",
"minLength": 1,
"description": "The link id (linkId), as returned by create_short_link or list_short_links"
}
},
"required": [
"groupId",
"linkId"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢get_group_visits(groupId, days)
Combined visit analytics for a group's current member links: totals {visits, qr, direct, bot} and a zero-filled per-day breakdown (UTC). Links removed from the group no longer count.
Input Schema
{
"type": "object",
"properties": {
"groupId": {
"type": "string",
"minLength": 1,
"description": "The group id (groupId), as returned by create_group or list_groups"
},
"days": {
"description": "How many UTC days back, including today: 1-365, default 30",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"groupId"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟡get_custom_domain
Get this tenant's custom (alias) domain and advance its setup as far as DNS allows. Use it to check progress after creating a DNS record. Lifecycle: pending_validation (create the certificate_validation record, and the optional ownership_verification TXT if listed) → provisioning (automatic, seconds) → pending_dns (create the routing CNAME from the domain to `target`) → active. Nothing advances on its own: call get_custom_domain after each DNS change to move it along. The response always carries `dnsRecords` (exact name/type/value to create, with `done` once seen) and `instructions` saying what to do next.
Input Schema
{
"type": "object",
"properties": {}
}🟡set_custom_domain(domain, payment)
Serve all of this tenant's short links on a domain it controls, e.g. "go.acme.com" → https://go.acme.com/{slug}. Once active, new short URLs and QR codes use it; links keep working on the platform domain too. One domain per tenant: setting a different one replaces (and tears down) the current one. Setting the same one again is harmless, and restarts it if it failed. Two DNS records are needed at the domain's DNS provider, returned one at a time: first a record (TXT or CNAME) that proves control (for the TLS certificate), then a CNAME pointing the domain at the platform. Lifecycle: pending_validation (create the certificate_validation record, and the optional ownership_verification TXT if listed) → provisioning (automatic, seconds) → pending_dns (create the routing CNAME from the domain to `target`) → active. Nothing advances on its own: call get_custom_domain after each DNS change to move it along. The response always carries `dnsRecords` (exact name/type/value to create, with `done` once seen) and `instructions` saying what to do next. Self-signed-up tenants (see /auth.md) pay once per new domain with x402: without a payment the tool returns an error whose structuredContent is an x402 PaymentRequired (x402Version 2, exact scheme, USDC). Retry with the signed PaymentPayload in the request's _meta["x402/payment"] (the x402 MCP transport), or, if your client cannot set _meta, in the `payment` argument. The settlement comes back in _meta["x402/payment-response"]. Re-setting the current domain, reading and removing are free; tenants given a key by an operator never pay.
Input Schema
{
"type": "object",
"properties": {
"domain": {
"type": "string",
"description": "Bare hostname you control, e.g. go.acme.com - no scheme, port or path"
},
"payment": {
"description": "Only if your client cannot send _meta[\"x402/payment\"]: the x402 PaymentPayload, as an object or base64",
"anyOf": [
{
"type": "string"
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
]
}
},
"required": [
"domain"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🔴remove_custom_domain
Remove this tenant's custom domain. Short links immediately stop resolving on it (QR codes printed with it break) and new short URLs use the platform domain. The DNS records can be deleted afterwards.
Input Schema
{
"type": "object",
"properties": {}
}Community
Evidence