Surli MCP

Surli MCP Server Overview

The Surli Model Context Protocol (MCP) Server connects AI assistants directly to Surli's URL shortener infrastructure, enabling AI models to programmatically create, manage, inspect, and update short links in real-time.

By integrating Surli's MCP Server into your AI agent or desktop workspace (Claude Desktop, Cursor, Google Antigravity, VS Code, Windsurf, etc.), your AI can autonomously shorten URLs, customize aliases, check quotas, and update destinations. Claude Desktop connects with zero API keys via native 1-click OAuth, while clients without OAuth (such as Google Antigravity, Windsurf, Zed, or CLI tools) authenticate by passing a Surli API key via HTTP headers (Authorization: Bearer and X-API-KEY).

Production MCP Server Endpoint

https://mcp.surl.li/mcp

Protocol: Model Context Protocol (MCP v2024-11-05) | Auth: Native 1-Click OAuth (Claude) & Header API Key (Antigravity/CLI) | Transports: HTTP & SSE

Key Features & Capabilities:

• Zero-friction URL Shortening: Create shortened URLs directly from AI chat conversations.
• Dynamic Destination Updates: Remap existing short link destinations on the fly.
• Custom Alias Management: Assign custom slugs/aliases to your short URLs.
• Real-Time Quota Tracking: Track link usage, plan tiers, and remaining monthly quota.
• Flexible Authentication: 1-click browser OAuth for Claude Desktop (zero keys required) and header-based API key auth (Authorization & X-API-KEY) for Google Antigravity & non-OAuth tools.

Quick Reference Architecture

Production Host:	mcp.surl.li
MCP Endpoint:	https://mcp.surl.li/mcp
OAuth Authorize:	https://mcp.surl.li/oauth/authorize
Metadata Discovery:	/.well-known/oauth-authorization-server
Auth Protocol:	OAuth 2.0 API Key
Tools Count:	5 Tools

Quickstart Guide (1-Minute Setup)

Connecting Surli MCP Server to your AI environment takes less than a minute. For Claude Desktop, no API key is needed (native 1-click OAuth). For Google Antigravity and other clients without OAuth, pass your Surli API key in headers.

Step 1

Production Endpoint

Use the production MCP server endpoint:

https://mcp.surl.li/mcp

Step 2

Configure Your Client

Claude Desktop (Zero API Key):

{"mcpServers":{"surli":{"url":"https://mcp.surl.li/mcp"}}}

Antigravity / Non-OAuth (API Key):

{"mcpServers":{"surli":{"serverUrl":"https://mcp.surl.li/mcp","headers":{"Authorization":"Bearer YOUR_API_KEY","X-API-KEY":"YOUR_API_KEY"}}}}

Step 3

Ask Your AI

Test your connection by asking your AI agent:

[!info] Info "Shorten https://github.com/surli with custom alias 'surli-mcp' using Surli tool."

What is MCP (Model Context Protocol)?

The Model Context Protocol (MCP) is an open specification created by Anthropic that standardizes how Artificial Intelligence applications (LLMs, AI agents, IDEs) communicate with external data sources, APIs, and tools.

Instead of custom API integrations for every single AI app, MCP provides a unified protocol supporting OAuth 2.0 and API Key (Bearer Token) authorization over standard transports like HTTP and SSE (Server-Sent Events).

How Surli MCP Server Works

1. Authentication: Clients with OAuth (like Claude Desktop) authenticate via native 1-click browser login with zero API keys, while non-OAuth clients (like Google Antigravity) authenticate by passing an API key in HTTP headers (Authorization: Bearer YOUR_API_KEY and X-API-KEY: YOUR_API_KEY).
2. Discovery: The AI client sends a tools/list JSON-RPC request to https://mcp.surl.li/mcp.
3. Capability Handshake: Surli MCP Server advertises available tools (create_short_link, get_short_link, etc.) along with JSON schemas.
4. Tool Execution: When a user asks an AI to shorten a link, the AI formats a tools/call JSON-RPC request.
5. Secure Execution: Surli MCP Server executes the request against Surli's user API and returns formatted results directly to the AI conversation.

Why Use Surli MCP Server?

• Flexible Auth: 1-click zero-key OAuth for Claude Desktop, or API key headers for Antigravity, CLI, and non-OAuth agents.
• No Code Required: You don't need to write custom cURL or SDK code; AI handles parameter parsing automatically.
• Safety & Scoping: Actions execute safely within your user plan limits and credentials.
• Universal Client Compatibility: Works across Claude Desktop, Cursor, Google Antigravity, VS Code, Windsurf, Zed, LibreChat, and custom SDKs.
• Real-Time Quota Awareness: AI agents inspect your remaining links before creating links to prevent quota errors.

Authentication Protocol

Surli MCP Server supports two authentication paths: Native 1-Click OAuth 2.0 (zero API keys needed) and API Key Headers (required for clients without OAuth).

[!warning] Warning

Important: Do I need an API Key?

• Claude Desktop (Native OAuth): NO API KEY NEEDED. Claude Desktop natively opens your browser for 1-click OAuth login. You do NOT need to configure or pass an API key at all!
• Google Antigravity, Headless CLI & Non-OAuth Clients: API KEY REQUIRED. Services and IDEs that do not support interactive browser OAuth MUST pass the Surli API key in HTTP headers (Authorization and X-API-KEY).

1. OAuth 2.0 (Claude Desktop & Browser Clients) No API Key Needed

Designed for desktop AI clients like Claude Desktop that support native RFC 8414 OAuth authorization. No API key is required — just supply the endpoint URL, and your client automatically opens a browser tab for 1-click login.

Endpoint URI	Description
/.well-known/oauth-authorization-server	RFC 8414 discovery endpoint.
https://mcp.surl.li/oauth/authorize	Browser authorization URL.
https://mcp.surl.li/oauth/token	Token exchange endpoint.

2. API Key Headers (Antigravity & Non-OAuth) API Key Required

Required only for clients without browser OAuth support (such as Google Antigravity, Windsurf, Zed, CLI daemons, and programmatic SDKs).

Required HTTP Headers:

Authorization: Bearer YOUR_API_KEY

X-API-KEY: YOUR_API_KEY

Configuration snippet:

{
  "mcpServers": {
    "surli": {
      "serverUrl": "https://mcp.surl.li/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "X-API-KEY": "YOUR_API_KEY"
      }
    }
  }
}

Passing both Authorization and X-API-KEY headers ensures immediate authentication across headless clients and proxies.

Endpoints & Transport Protocol

Surli MCP Server supports both API Key (Authorization & X-API-KEY) authentication and OAuth 2.0 Authorization alongside standard HTTP JSON-RPC and Server-Sent Events (SSE) streaming transports.

Endpoint	Method	Type / Protocol	Description
https://mcp.surl.li/mcp	GET / POST	Unified MCP Endpoint	Primary production MCP endpoint with support for API Key (Authorization & X-API-KEY) and OAuth 2.0 auth.
https://mcp.surl.li/oauth/authorize	GET	OAuth 2.0 Authorize	Browser login flow for AI client OAuth 2.0 token authorization.
https://mcp.surl.li/oauth/token	POST	OAuth 2.0 Token	Exchange OAuth code/refresh token for MCP access credentials.
https://mcp.surl.li/mcp/sse	GET	SSE (Server-Sent Events)	Streaming SSE transport session endpoint.
https://mcp.surl.li/mcp/messages	POST	HTTP JSON-RPC 2.0	Handles raw initialize, tools/list, and tools/call RPC messages.

AI Client Setup Configurations (11+ Supported AI Clients)

Surli MCP Server supports two authentication paths: Native 1-Click OAuth 2.0 and API Key Headers.

When is an API Key required vs. NOT required?

Claude Desktop: NO API Key Needed!

Claude Desktop supports native 1-click browser OAuth. You do NOT need to pass or configure any API key! Simply provide the URL https://mcp.surl.li/mcp and authenticate in 1 click in your browser.

Antigravity & Non-OAuth: API Key Strictly Required

Clients and IDEs that do not have browser OAuth (such as Google Antigravity, Windsurf, Zed, CLI scripts, and SDKs) MUST pass the Surli API key in headers (Authorization and X-API-KEY) using serverUrl.

File location: %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

[!success] Success Zero API Keys Required: Claude Desktop connects natively via OAuth 2.0. You do NOT need to pass any API key! Just add the endpoint URL, and Claude will automatically open your browser to log in:

{
  "mcpServers": {
    "surli": {
      "url": "https://mcp.surl.li/mcp"
    }
  }
}

Headless/testing note: An API key is only needed if you are running in a headless environment without browser access, in which case you can pass "headers": { "Authorization": "Bearer YOUR_API_KEY", "X-API-KEY": "YOUR_API_KEY" }.

Cursor supports both native OAuth and direct API key configuration:

Option A: 1-Click OAuth (No API Key Required)

In Cursor Settings → Features → MCP Servers, add new server with type SSE / OAuth and URL https://mcp.surl.li/mcp, or add to .cursor/mcp.json:

{"mcpServers":{"surli":{"url":"https://mcp.surl.li/mcp"}}}

Option B: Direct API Key Headers

If not using OAuth, configure your Surli API key in headers:

{
  "mcpServers": {
    "surli": {
      "serverUrl": "https://mcp.surl.li/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "X-API-KEY": "YOUR_API_KEY"
      }
    }
  }
}

In VS Code Roo Code settings (mcp_settings.json), add the Surli MCP server configuration:

{
  "mcpServers": {
    "surli": {
      "serverUrl": "https://mcp.surl.li/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "X-API-KEY": "YOUR_API_KEY"
      }
    }
  }
}

Edit cline_mcp_settings.json:

{
  "mcpServers": {
    "surli": {
      "serverUrl": "https://mcp.surl.li/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "X-API-KEY": "YOUR_API_KEY"
      }
    }
  }
}

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "surli": {
      "serverUrl": "https://mcp.surl.li/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "X-API-KEY": "YOUR_API_KEY"
      }
    }
  }
}

Continue Plugin

Edit ~/.continue/config.json under experimental.mcpServers:

{
  "experimental": {
    "mcpServers": [
      {
        "name": "surli",
        "url": "https://mcp.surl.li/mcp",
        "requestOptions": {
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY",
            "X-API-KEY": "YOUR_API_KEY"
          }
        }
      }
    ]
  }
}

Zed Editor

Edit ~/.config/zed/settings.json under context_servers:

{
  "context_servers": {
    "surli": {
      "settings": {
        "serverUrl": "https://mcp.surl.li/mcp",
        "headers": {
          "Authorization": "Bearer YOUR_API_KEY",
          "X-API-KEY": "YOUR_API_KEY"
        }
      }
    }
  }
}

Goose CLI

Edit ~/.config/goose/config.yaml:

mcp_servers:
  surli:
    serverUrl: https://mcp.surl.li/mcp
    headers:
      Authorization: "Bearer YOUR_API_KEY"
      X-API-KEY: "YOUR_API_KEY"

Add to your librechat.yaml under mcpServers:

mcpServers:
  surli:
    serverUrl: https://mcp.surl.li/mcp
    headers:
      Authorization: "Bearer YOUR_API_KEY"
      X-API-KEY: "YOUR_API_KEY"

[!warning] Warning API Key Strictly Required: Antigravity does not support interactive browser OAuth login. You MUST provide your Surli API Key in headers (both Authorization and X-API-KEY) with serverUrl.

Configure in ~/.gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "surli": {
      "serverUrl": "https://mcp.surl.li/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "X-API-KEY": "YOUR_API_KEY"
      }
    }
  }
}

Passing both Authorization: Bearer YOUR_API_KEY and X-API-KEY: YOUR_API_KEY headers guarantees that Antigravity connects and authenticates on startup.

Programmatic SDKs

Python SDK (mcp package):

from mcp import ClientSession
from mcp.client.http import http_client

async def run_surli():
    headers = {
        "Authorization": "Bearer YOUR_API_KEY",
        "X-API-KEY": "YOUR_API_KEY"
    }
    async with http_client("https://mcp.surl.li/mcp", headers=headers) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print("Connected to Surli MCP! Tools available:", [t.name for t in tools.tools])

Node.js / TypeScript SDK (@modelcontextprotocol/sdk):

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { HTTPClientTransport } from "@modelcontextprotocol/sdk/client/http.js";

const transport = new HTTPClientTransport(new URL("https://mcp.surl.li/mcp"), {
  requestInit: {
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "X-API-KEY": "YOUR_API_KEY"
    }
  }
});
const client = new Client({ name: "SurliAgent", version: "1.0.0" }, { capabilities: {} });
await client.connect(transport);

const tools = await client.listTools();
console.log("Surli Tools:", tools);

Usage Examples & AI Prompts

Once Surli MCP Server is enabled in your AI agent, you can talk to your AI in plain conversational language. The AI agent will automatically call the appropriate Surli MCP tool.

Prompt: Shorten Links

"Hey, please shorten this destination link https://github.com/hypermans/dev-surli with custom alias 'dev-surli' and title 'Dev Surli Repo'."

[!secondary] Secondary AI Action: Calls create_short_link(destination_url='...', alias='dev-surli', title='Dev Surli Repo') and displays result.

Prompt: Check Account Quota

"How many short links do I have left in my Surli account for this month?"

[!secondary] Secondary AI Action: Calls get_account_limits() and reports plan tier, used count, and remaining quota.

Prompt: Update Link Destination

"Change the destination of link 'dev-surli' to point to https://surl.li/docs instead."

[!secondary] Secondary AI Action: Calls update_destination(surl='dev-surli', new_destination_url='https://surl.li/docs').

Prompt: Change Alias

"Update the alias of link 'dev-surli' to 'surli-api'."

[!secondary] Secondary AI Action: Calls update_alias(surl='dev-surli', new_alias='surli-api').