Voyal / MCP
MCP server
The MCP server is a stateless Streamable HTTP endpoint at https://app.voyal.link/mcp. It identifies itself as links version 0.3.0. A connection accepts a Clerk OAuth access token or a Clerk API key, and acts on one organization.
Connect with OAuth
Add the server URL in Claude, Cursor, or any MCP client that supports remote OAuth. The client discovers the authorization server from this origin and asks you to sign in. The consent screen asks which organization to grant. That organization is the only one the connection can use. To work in another organization, add another account in the client.
Requested scopes: profile, email, user:org:read.
- Protected resource metadata:https://app.voyal.link/.well-known/oauth-protected-resource/mcp(also at
/.well-known/oauth-protected-resource) - Authorization server metadata:https://app.voyal.link/.well-known/oauth-authorization-server
- OpenID configuration, for clients that look it up on this origin:https://app.voyal.link/.well-known/openid-configuration
Claude Code
claude mcp add --transport http links https://app.voyal.link/mcpConnect with an API key
For a client without OAuth, create a key in the app while the organization is active. Open MCP & API and create a key there. Keys created while an organization is active belong to that organization. Send the key as a bearer token. The same key also authenticates the REST API at /api/links and /api/domains.
The command below uses the placeholder <API_KEY>. Replace it with a key from your account. It is not a working credential, and a real key should not be committed or pasted into a public page.
claude mcp add --transport http links https://app.voyal.link/mcp --header "Authorization: Bearer <API_KEY>"add_domain and update_domain require an organization admin. An organization API key counts as an admin. The other link tools are available to members.
Link settings
Refer to a link by its id, by hostname/slug, or by a bare slug when that slug is unique across your domains. If the same slug exists on more than one domain, pass hostname/slug.
- url
- Destination URL (http or https). Required when creating a link.
- title
- Optional label, up to 200 characters.
- enabled
- Disabled links return 404, or the domain not-found URL when one is set. Default is enabled.
- redirectCode
- 301, 302, 307, or 308. Default 302.
- forwardQuery
- When on (the default), append the visitor query string to the chosen destination if that parameter is not already there. This forwards UTM parameters. It applies to the normal destination, not to the not-found or expired redirect.
- iosUrl
- Destination when the user agent identifies an iPhone, iPad, or iPod, and no country rule matched.
- androidUrl
- Destination when the user agent identifies Android, and no country or iOS rule matched.
- geo
- Map of a two-letter ISO country code (for example "MX") to a destination URL. Country is checked before device rules, using the country on the Cloudflare request.
- expiresAt
- ISO 8601 expiration. After that time, visitors are sent to expiredUrl, or receive HTTP 410 when expiredUrl is empty.
- expiredUrl
- Where to send visitors after expiry. Pass null on update to clear it.
- note
- Context for your team (why the link exists, campaign, owner), up to 2000 characters.
- domain
- Hostname of one of your domains. On create, it may be omitted when the organization has exactly one domain. On update, it moves the link.
- slug
- Custom slug. Letters, numbers, "-", and "_", with "/" between segments (for example "team/victor"), up to 64 characters. Omitted on create, a random slug is used. The slug "_root" is the domain root: its public URL is https://hostname/ with no slug in the path.
Tools
These are the tools the server registers. Names and descriptions match that registration.
create_link— Create short linkShorten a URL on one of your domains, with optional custom slug, device/geo targeting and expiration. Use slug "_root" to set what the domain root URL redirects to.
Input. url, plus any link settings. domain and slug are optional, with the rules above.
list_links— List short linksList your short links, newest first.
Input. domain (optional), limit (1–500, default 50), offset (default 0). Read-only.
get_link— Get short linkGet a link with its full configuration, including its last health check (checkedAt, checkStatus, checkError). Use check_link to confirm the destination status right now.
Input. link. Read-only.
list_broken_links— List broken or expired linksLinks whose destination failed the scheduled health check (4xx/5xx, timeout, or unreachable) and/or that have expired. The schedule rechecks links that have not been checked in the last 7 days. Broken results come from the last stored check; use check_link to confirm a link is still broken.
Input. problem ("broken" or "expired", optional; both when omitted), domain, limit (1–500, default 50), offset (default 0). Read-only.
check_link— Check link destinations nowFetch every destination of a link (main, iOS, Android, and geo URLs) right now, store the result, and return the updated link. Use it to confirm a reported breakage or that a fix worked.
Input. link. Returns the link and healthy, which is true when checkError is null.
update_link— Update short linkChange any setting of a link. Pass null to clear an optional setting.
Input. link, plus any link settings. url is optional here. domain moves the link. slug changes the slug.
delete_link— Delete short linkPermanently delete a link and its click history.
Input. link. Destructive.
get_link_stats— Get link analyticsClicks over time plus top countries, cities, referrers, devices, browsers and OS for a link.
Input. link, days (1–365, default 30), includeBots (default false). Read-only. The click counter on the link leaves bots out. periodClicks follows includeBots. Cities are "city, country". Referrers are the referring host.
list_domains— List custom domainsList your custom domains.
Input. No inputs. Read-only.
add_domain— Add custom domainRegister a hostname on this organization. Requests for it are matched to the organization. The hostname must also be routed to the Voyal Worker.
Input. hostname, for example go.example.com. Organization admins only. An organization API key counts as an admin.
update_domain— Update custom domainSet where unknown slugs redirect. To configure the root URL, create or update the "_root" link on the domain.
Input. domain (id or hostname) and notFoundUrl. null shows a 404. Organization admins only.
get_organization— Get organizationThe organization this connection acts on (chosen when signing in). Connect another account to use another organization.
Input. No inputs. Read-only. Returns id, name, slug, and role ("admin" or "member").