MCP Server

This page is the parameter-level reference. To connect a specific assistant step by step, follow How do I connect an AI assistant to Flyn with MCP?; for an overview of what an assistant can do with Flyn, see Flyn for AI assistants.

Transport

• Streamable HTTP, stateless. Every message is a JSON-RPC 2.0 request sent as an HTTP POST to the endpoint, and every reply is a single JSON response. The server never opens an event stream and keeps no session, so GET and DELETE answer 405.
• Protocol versions: 2025-06-18 and 2025-03-26. initialize echoes the version you request when it is one of these and otherwise answers with 2025-06-18. Responses with a JSON-RPC body carry an MCP-Protocol-Version header.
• Batches (a 2025-03-26 feature) are accepted, up to 20 messages per request, and get a batch response.
• CORS is open (Access-Control-Allow-Origin: *, preflight answers 204), so browser-based clients can call it. Credentials are only ever a Bearer token, never a cookie.
• Capabilities: tools only, with listChanged: false.

Methods

Discovery needs no credentials, so a client can list the tools before it signs in. A batch that contains any method needing credentials is checked as a whole.

curl -X POST https://www.flyn.to/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "my-client", "version": "1.0.0" }
    }
  }'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": { "tools": { "listChanged": false } },
    "serverInfo": { "name": "flyn", "title": "Flyn Link Shortener", "version": "1.0.0" },
    "instructions": "Flyn creates and manages short links (flyn.to) with click analytics. ..."
  }
}

Authentication

tools/call needs one of two credentials, sent as Authorization: Bearer ... on every request.

• OAuth sign-in, on every plan including Free. A client that supports OAuth adds the endpoint with no key. Its first unauthenticated tool call gets a 401 whose WWW-Authenticate header points to the protected-resource metadata, and from there the client opens the Flyn sign-in and consent page and receives an access token. There is no plan check anywhere in this flow.
• API key, on Pro, Lifetime or Team. Send Bearer flyn_sk_live_..., the same key the REST API takes. Keys are created in Settings, API Keys, and creating one needs a paid plan; an account can hold up to 5 active keys. See Authentication.

OAuth details

The token endpoint accepts public clients and client credentials in the body or in an HTTP Basic header. Every authorization response carries an iss parameter (RFC 9207). A user can revoke a client at any time under Settings, Connected Apps; its next call is rejected.

Which calls an OAuth token reaches

An OAuth access token belongs to the MCP connection, not to the account at large. Outside /mcp it is accepted only by the few REST operations listed on the OpenAPI page, and it cannot create API keys or reach webhooks, domains, billing or account settings.

Plan limits

Every tool calls the same route as the REST API, so the account's plan applies exactly as it does in the dashboard. The MCP layer adds no gate of its own.

• Free accounts can create 25 links per calendar month (UTC), counted per account, or per workspace inside a team. The next create returns an error result naming the limit.
• Where a description below says Pro, the gate is any paid plan: Pro, Lifetime or Team. On Free, a call that uses such an input returns an error result naming the feature, with a link to pricing, and nothing is created or changed.
• On Free, get_link_analytics returns timestamps and counts, with the location, device and referrer fields set to null, for the last 30 days.
• Team role permissions apply as they do in the dashboard, for example a viewer cannot edit links.

Tools

The 8 tools tools/list returns. Descriptions are the ones the server sends to the model, word for word; parameter rows are condensed and add the schema constraints. Each tool also carries the four MCP annotation hints shown under its name; they are advisory, for clients that ask before running a destructive tool.

Rotation destinations

The item shape of rotation in create_short_link and update_link. The schema allows no other properties; the server ignores extra ones rather than rejecting them.

update_link's rotation description ends with this text, and create_short_link's has it just before its closing Safe Browsing sentence:

Up to 12 destinations; sending more is rejected rather than truncated, so nothing is dropped without telling you. Each human visitor is sent to one destination drawn at random in proportion to its weight, so the split settles over many clicks rather than following a strict order. Bots and crawlers always get the primary url, which stays required. Each click records the id of the destination that served it, and that id, not the url and not the list position, is what per-destination stats are keyed on. The Flyn dashboard does report them: the link's own analytics page has a "Destination Performance" panel listing every destination with its click count, its actual share of clicks, and the share its weight intended, and it keeps showing a destination you later remove from the rotation. No API or MCP call returns that breakdown, or the per-click destination id, so send the user to that page rather than inventing a tool call for it. The panel counts clicks only, across the clicks that carry a destination id: no conversion or revenue split, and no winner declared.

Tool results

• On success, content holds one text block with the REST response body as pretty-printed JSON.
• The two QR tools, in PNG format (the default), return an image block (base64) plus a text block summarising the code; the base64 is not repeated in the text. With format: "svg" there is no image block and the markup is in the text block, unless it is over 8,000 characters, in which case a note says to request PNG or call the REST route.
• A failed call is still a JSON-RPC result, with isError: true and the API's error message as text, so the model can read it and correct itself. Plan errors add a link to pricing, 401s add where to create an API key, and 429s say the limit is temporary and to wait about a minute.

curl -X POST https://www.flyn.to/mcp \
  -H "Authorization: Bearer flyn_sk_live_..." \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "create_short_link",
      "arguments": { "url": "https://example.com/spring-sale", "slug": "spring-sale" }
    }
  }'

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      { "type": "text", "text": "<the POST /api/links response body, as pretty-printed JSON>" }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "Password protection is only available on Pro or Lifetime. Upgrade at /pricing. This is a Flyn Pro feature: https://www.flyn.to/pricing"
      }
    ]
  }
}

Errors and limits

What the endpoint itself returns, before any tool runs. Oversized bodies are refused before authentication, so an anonymous request cannot make the server parse more than 256 KB declared, or 262,144 characters on a chunked body.

Each tool is also limited by its own REST route, per client IP, as listed under each tool above. See Rate Limits and Errors for those routes.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://www.flyn.to/.well-known/oauth-protected-resource/mcp"

{
  "error": "unauthorized",
  "message": "The Flyn MCP server needs credentials, and there are two ways to give them. Easiest: if your client supports OAuth, add https://www.flyn.to/mcp with no key and it will open a Flyn sign-in page. That works on any plan, the free one included. Otherwise send \"Authorization: Bearer flyn_sk_live_...\" with every request; API keys are created at https://www.flyn.to/settings?tab=api and require a paid plan (Pro, Lifetime or Team). Setup guide: https://www.flyn.to/ai"
}

Related

• Connect an AI assistant with MCP: the step-by-step setup for each client.
• Flyn for AI assistants: what an assistant can do with Flyn.
• OpenAPI Specification: the REST API the tools run on.