Surli MCP

Crea y gestiona enlaces cortos desde ChatGPT, Claude, Cursor y otras herramientas de IA a través de MCP.

Documentación

Descripción General del Servidor Surli MCP

El Servidor Surli Model Context Protocol (MCP) conecta asistentes de IA directamente con la infraestructura de acortador de URLs de Surli, permitiendo que los modelos de IA creen, gestionen, inspeccionen y actualicen enlaces cortos de forma programática y en tiempo real.

Al integrar el Servidor MCP de Surli en tu agente de IA o espacio de trabajo de escritorio (Claude Desktop, Cursor, Google Antigravity, VS Code, Windsurf, etc.), tu IA puede acortar URLs de forma autónoma, personalizar alias, verificar cuotas y actualizar destinos. Claude Desktop se conecta sin claves API mediante OAuth nativo de 1 clic, mientras que los clientes sin OAuth (como Google Antigravity, Windsurf, Zed o herramientas CLI) se autentican pasando una clave API de Surli a través de encabezados HTTP (Authorization: Bearer y X-API-KEY).

Endpoint del Servidor MCP de Producción

https://mcp.surl.li/mcp

Protocolo: Model Context Protocol (MCP v2024-11-05) | Autenticación: OAuth nativo de 1 clic (Claude) y Clave API en encabezado (Antigravity/CLI) | Transportes: HTTP y SSE

Características y Capacidades Clave:

Acortamiento de URLs sin fricción: Crea URLs acortadas directamente desde conversaciones de chat con IA.
Actualización dinámica de destinos: Reasigna destinos de enlaces cortos existentes sobre la marcha.
Gestión de alias personalizados: Asigna slugs/alias personalizados a tus URLs cortas.
Seguimiento de cuota en tiempo real: Rastrea el uso de enlaces, niveles de plan y cuota mensual restante.
Autenticación flexible: OAuth de navegador de 1 clic para Claude Desktop (cero claves requeridas) y autenticación por clave API en encabezado (Authorization y X-API-KEY) para Google Antigravity y herramientas sin OAuth.

Arquitectura de Referencia Rápida

Host de Producción:	`mcp.surl.li`
Endpoint MCP:	`https://mcp.surl.li/mcp`
Autorización OAuth:	`https://mcp.surl.li/oauth/authorize`
Descubrimiento de Metadatos:	`/.well-known/oauth-authorization-server`
Protocolo de Autenticación:	Clave API OAuth 2.0
Número de Herramientas:	5 Herramientas

Guía de Inicio Rápido (Configuración en 1 Minuto)

Conectar el Servidor MCP de Surli a tu entorno de IA toma menos de un minuto. Para Claude Desktop, no se necesita clave API (OAuth nativo de 1 clic). Para Google Antigravity y otros clientes sin OAuth, pasa tu clave API de Surli en los encabezados.

Paso 1

Endpoint de Producción

Usa el endpoint del servidor MCP de producción:

https://mcp.surl.li/mcp

Paso 2

Configura tu Cliente

Claude Desktop (Cero Claves API):

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

Antigravity / Sin OAuth (Clave API):

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

Paso 3

Pregunta a tu IA

Prueba tu conexión preguntando a tu agente de IA:

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

¿Qué es MCP (Model Context Protocol)?

El Model Context Protocol (MCP) es una especificación abierta creada por Anthropic que estandariza cómo las aplicaciones de Inteligencia Artificial (LLMs, agentes de IA, IDEs) se comunican con fuentes de datos externas, APIs y herramientas.

En lugar de integraciones API personalizadas para cada aplicación de IA, MCP proporciona un protocolo unificado que admite OAuth 2.0 y Clave API (Bearer Token) como autorización sobre transportes estándar como HTTP y SSE (Server-Sent Events).

Cómo Funciona el Servidor MCP de Surli

Autenticación: Los clientes con OAuth (como Claude Desktop) se autentican mediante inicio de sesión nativo de navegador de 1 clic con cero claves API, mientras que los clientes sin OAuth (como Google Antigravity) se autentican pasando una clave API en los encabezados HTTP (Authorization: Bearer YOUR_API_KEY y X-API-KEY: YOUR_API_KEY).
Descubrimiento: El cliente de IA envía una solicitud JSON-RPC tools/list a https://mcp.surl.li/mcp.
Protocolo de Capacidades: El Servidor MCP de Surli anuncia las herramientas disponibles (create_short_link, get_short_link, etc.) junto con esquemas JSON.
Ejecución de Herramientas: Cuando un usuario pide a una IA acortar un enlace, la IA formatea una solicitud JSON-RPC tools/call.
Ejecución Segura: El Servidor MCP de Surli ejecuta la solicitud contra la API de usuario de Surli y devuelve resultados formateados directamente a la conversación de IA.

¿Por Qué Usar el Servidor MCP de Surli?

Autenticación Flexible: OAuth de 1 clic sin claves para Claude Desktop, o encabezados de clave API para Antigravity, CLI y agentes sin OAuth.
Sin Código Requerido: No necesitas escribir código cURL o SDK personalizado; la IA maneja el análisis de parámetros automáticamente.
Seguridad y Alcance: Las acciones se ejecutan de forma segura dentro de los límites de tu plan de usuario y credenciales.
Compatibilidad Universal con Clientes: Funciona en Claude Desktop, Cursor, Google Antigravity, VS Code, Windsurf, Zed, LibreChat y SDKs personalizados.
Conciencia de Cuota en Tiempo Real: Los agentes de IA inspeccionan tus enlaces restantes antes de crear enlaces para prevenir errores de cuota.

Protocolo de Autenticación

El Servidor MCP de Surli admite dos rutas de autenticación: OAuth 2.0 nativo de 1 clic (cero claves API necesarias) y Encabezados de Clave API (requerido para clientes sin OAuth).

[!warning] Advertencia

Importante: ¿Necesito una Clave API?

Claude Desktop (OAuth Nativo): NO SE NECESITA CLAVE API. Claude Desktop abre nativamente tu navegador para inicio de sesión OAuth de 1 clic. NO necesitas configurar ni pasar una clave API en absoluto.

Google Antigravity, CLI sin Interfaz y Clientes sin OAuth: CLAVE API REQUERIDA. Los servicios e IDEs que no admiten OAuth interactivo de navegador DEBEN pasar la clave API de Surli en los encabezados HTTP (Authorization y X-API-KEY).

1. OAuth 2.0 (Claude Desktop y Clientes de Navegador) Sin Necesidad de Clave API

Diseñado para clientes de IA de escritorio como Claude Desktop que admiten autorización OAuth nativa RFC 8414. No se requiere clave API — solo proporciona la URL del endpoint, y tu cliente abrirá automáticamente una pestaña del navegador para inicio de sesión de 1 clic.

URI del Endpoint	Descripción
`/.well-known/oauth-authorization-server`	Endpoint de descubrimiento RFC 8414.
`https://mcp.surl.li/oauth/authorize`	URL de autorización del navegador.
`https://mcp.surl.li/oauth/token`	Endpoint de intercambio de tokens.

2. Encabezados de Clave API (Antigravity y Sin OAuth) Clave API Requerida

Requerido solo para clientes sin soporte OAuth de navegador (como Google Antigravity, Windsurf, Zed, demonios CLI y SDKs programáticos).

Encabezados HTTP Requeridos:

Authorization: Bearer YOUR_API_KEY

X-API-KEY: YOUR_API_KEY

Fragmento de configuración:

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

Pasar ambos encabezados Authorization y X-API-KEY garantiza autenticación inmediata en clientes sin interfaz y proxies.

Endpoints y Protocolo de Transporte

El Servidor MCP de Surli admite tanto autenticación por Clave API (Authorization y X-API-KEY) como Autorización OAuth 2.0 junto con transportes estándar de HTTP JSON-RPC y Server-Sent Events (SSE).

Endpoint	Método	Tipo / Protocolo	Descripción
`https://mcp.surl.li/mcp`	GET / POST	Endpoint MCP Unificado	Endpoint MCP principal de producción con soporte para Clave API (`Authorization` y `X-API-KEY`) y autenticación OAuth 2.0.
`https://mcp.surl.li/oauth/authorize`	GET	Autorización OAuth 2.0	Flujo de inicio de sesión en navegador para autorización de token OAuth 2.0 del cliente de IA.
`https://mcp.surl.li/oauth/token`	POST	Token OAuth 2.0	Intercambia código OAuth/token de actualización por credenciales de acceso MCP.
`https://mcp.surl.li/mcp/sse`	GET	SSE (Server-Sent Events)	Endpoint de sesión de transporte SSE en streaming.
`https://mcp.surl.li/mcp/messages`	POST	HTTP JSON-RPC 2.0	Maneja mensajes RPC `initialize`, `tools/list` y `tools/call` sin procesar.

Configuraciones de Cliente de IA (11+ Clientes de IA Compatibles)

El Servidor MCP de Surli admite dos rutas de autenticación: OAuth 2.0 nativo de 1 clic y Encabezados de Clave API.

¿Cuándo se requiere una Clave API vs. NO se requiere?

Claude Desktop: ¡NO se necesita Clave API!

Claude Desktop admite OAuth nativo de navegador de 1 clic. NO necesitas pasar ni configurar ninguna clave API. Simplemente proporciona la URL https://mcp.surl.li/mcp y autentícate en 1 clic en tu navegador.

Antigravity y Sin OAuth: Clave API Estrictamente Requerida

Los clientes e IDEs que no tienen OAuth de navegador (como Google Antigravity, Windsurf, Zed, scripts CLI y SDKs) DEBEN pasar la clave API de Surli en headers (Authorization y X-API-KEY) usando serverUrl.

Ubicación del archivo: %APPDATA%\Claude\claude_desktop_config.json (Windows) o ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

[!success] Éxito Cero Claves API Requeridas: Claude Desktop se conecta nativamente mediante OAuth 2.0. NO necesitas pasar ninguna clave API. Solo agrega la URL del endpoint, y Claude abrirá automáticamente tu navegador para iniciar sesión:

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

Nota para entornos sin interfaz/pruebas: Solo se necesita una clave API si estás ejecutando en un entorno sin interfaz sin acceso a navegador, en cuyo caso puedes pasar "headers": { "Authorization": "Bearer YOUR_API_KEY", "X-API-KEY": "YOUR_API_KEY" }.

Cursor admite tanto OAuth nativo como configuración directa de clave API:

Opción A: OAuth de 1 Clic (Sin Clave API Requerida)

En Configuración de Cursor → Funciones → Servidores MCP, agrega un nuevo servidor con tipo SSE / OAuth y URL https://mcp.surl.li/mcp, o agrégalo a .cursor/mcp.json:

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

Opción B: Encabezados Directos de Clave API

Si no usas OAuth, configura tu clave API de Surli en headers:

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

En la configuración de VS Code Roo Code (mcp_settings.json), agrega la configuración del servidor MCP de Surli:

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

Edita cline_mcp_settings.json:

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

Edita ~/.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"
      }
    }
  }
}

Plugin Continue

Edita ~/.continue/config.json bajo 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"
          }
        }
      }
    ]
  }
}

Editor Zed

Edita ~/.config/zed/settings.json bajo context_servers:

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

CLI Goose

Edita ~/.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"

Agrega a tu librechat.yaml bajo mcpServers:

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

[!warning] Advertencia Clave API Estrictamente Requerida: Antigravity no admite inicio de sesión OAuth interactivo de navegador. DEBES proporcionar tu Clave API de Surli en headers (tanto Authorization como X-API-KEY) con serverUrl.

Configura en ~/.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"
      }
    }
  }
}

Pasar ambos encabezados Authorization: Bearer YOUR_API_KEY y X-API-KEY: YOUR_API_KEY garantiza que Antigravity se conecte y autentique al inicio.

SDKs Programáticos

SDK de Python (paquete mcp):

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])

SDK de Node.js / TypeScript (@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);

Ejemplos de Uso y Prompts de IA

Una vez que el Servidor MCP de Surli está habilitado en tu agente de IA, puedes hablar con tu IA en lenguaje conversacional simple. El agente de IA llamará automáticamente a la herramienta MCP de Surli apropiada.

Prompt: Acortar Enlaces

"Oye, por favor acorta este enlace de destino https://github.com/hypermans/dev-surli con el alias personalizado 'dev-surli' y el título 'Dev Surli Repo'."

[!secondary] Secundario Acción de IA: Llama a create_short_link(destination_url='...', alias='dev-surli', title='Dev Surli Repo') y muestra el resultado.

Prompt: Verificar Cuota de Cuenta

"¿Cuántos enlaces cortos me quedan en mi cuenta de Surli para este mes?"

[!secondary] Secundario Acción de IA: Llama a get_account_limits() e informa el nivel del plan, el conteo usado y la cuota restante.

Prompt: Actualizar Destino del Enlace

"Cambia el destino del enlace 'dev-surli' para que apunte a https://surl.li/docs en su lugar."

[!secondary] Secundario Acción de IA: Llama a update_destination(surl='dev-surli', new_destination_url='https://surl.li/docs').

Prompt: Cambiar Alias

"Actualiza el alias del enlace 'dev-surli' a 'surli-api'."

[!secondary] Secundario Acción de IA: Llama a update_alias(surl='dev-surli', new_alias='surli-api').