Surli MCP

Crie e gerencie links curtos a partir do ChatGPT, Claude, Cursor e outras ferramentas de IA via MCP.

Documentação

Visão Geral do Servidor Surli MCP

O Servidor Surli Model Context Protocol (MCP) conecta assistentes de IA diretamente à infraestrutura de encurtamento de URLs da Surli, permitindo que modelos de IA criem, gerenciem, inspecionem e atualizem links curtos programaticamente em tempo real.

Ao integrar o Servidor MCP da Surli ao seu agente de IA ou ambiente de trabalho desktop (Claude Desktop, Cursor, Google Antigravity, VS Code, Windsurf, etc.), sua IA pode encurtar URLs de forma autônoma, personalizar aliases, verificar cotas e atualizar destinos. O Claude Desktop conecta-se sem chaves de API via OAuth nativo com 1 clique, enquanto clientes sem OAuth (como Google Antigravity, Windsurf, Zed ou ferramentas CLI) autenticam-se passando uma chave de API da Surli via cabeçalhos HTTP (Authorization: Bearer e X-API-KEY).

Endpoint do Servidor MCP de Produção

https://mcp.surl.li/mcp

Protocolo: Model Context Protocol (MCP v2024-11-05) | Autenticação: OAuth nativo com 1 clique (Claude) e Chave de API via Cabeçalho (Antigravity/CLI) | Transportes: HTTP e SSE

Principais Recursos e Capacidades:

Encurtamento de URLs sem Atrito: Crie URLs encurtadas diretamente de conversas de chat com IA.
Atualizações Dinâmicas de Destino: Remapeie destinos de links curtos existentes em tempo real.
Gerenciamento de Aliases Personalizados: Atribua slugs/aliases personalizados às suas URLs curtas.
Monitoramento de Cota em Tempo Real: Acompanhe o uso de links, níveis de plano e cota mensal restante.
Autenticação Flexível: OAuth via navegador com 1 clique para Claude Desktop (zero chaves necessárias) e autenticação por chave de API via cabeçalho (Authorization e X-API-KEY) para Google Antigravity e ferramentas sem OAuth.

Arquitetura de Referência Rápida

Host de Produção:	`mcp.surl.li`
Endpoint MCP:	`https://mcp.surl.li/mcp`
Autorização OAuth:	`https://mcp.surl.li/oauth/authorize`
Descoberta de Metadados:	`/.well-known/oauth-authorization-server`
Protocolo de Autenticação:	Chave de API OAuth 2.0
Número de Ferramentas:	5 Ferramentas

Guia de Início Rápido (Configuração em 1 Minuto)

Conectar o Servidor Surli MCP ao seu ambiente de IA leva menos de um minuto. Para Claude Desktop, nenhuma chave de API é necessária (OAuth nativo com 1 clique). Para Google Antigravity e outros clientes sem OAuth, passe sua chave de API da Surli nos cabeçalhos.

Etapa 1

Endpoint de Produção

Use o endpoint do servidor MCP de produção:

https://mcp.surl.li/mcp

Etapa 2

Configure Seu Cliente

Claude Desktop (Zero Chave de API):

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

Antigravity / Sem OAuth (Chave de API):

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

Etapa 3

Pergunte à Sua IA

Teste sua conexão perguntando ao seu agente de IA:

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

O que é MCP (Model Context Protocol)?

O Model Context Protocol (MCP) é uma especificação aberta criada pela Anthropic que padroniza como aplicações de Inteligência Artificial (LLMs, agentes de IA, IDEs) se comunicam com fontes de dados externas, APIs e ferramentas.

Em vez de integrações de API personalizadas para cada aplicativo de IA, o MCP fornece um protocolo unificado que suporta OAuth 2.0 e autorização por Chave de API (Bearer Token) em transportes padrão como HTTP e SSE (Server-Sent Events).

Como Funciona o Servidor Surli MCP

Autenticação: Clientes com OAuth (como Claude Desktop) autenticam-se via login nativo no navegador com 1 clique e zero chaves de API, enquanto clientes sem OAuth (como Google Antigravity) autenticam-se passando uma chave de API nos cabeçalhos HTTP (Authorization: Bearer YOUR_API_KEY e X-API-KEY: YOUR_API_KEY).
Descoberta: O cliente de IA envia uma solicitação JSON-RPC tools/list para https://mcp.surl.li/mcp.
Handshake de Capacidades: O Servidor Surli MCP anuncia as ferramentas disponíveis (create_short_link, get_short_link, etc.) juntamente com os esquemas JSON.
Execução de Ferramentas: Quando um usuário pede a uma IA para encurtar um link, a IA formata uma solicitação JSON-RPC tools/call.
Execução Segura: O Servidor Surli MCP executa a solicitação contra a API de usuário da Surli e retorna resultados formatados diretamente para a conversa de IA.

Por que Usar o Servidor Surli MCP?

Autenticação Flexível: OAuth com 1 clique e zero chaves para Claude Desktop, ou cabeçalhos de chave de API para Antigravity, CLI e agentes sem OAuth.
Sem Necessidade de Código: Você não precisa escrever código cURL ou SDK personalizado; a IA lida com a análise de parâmetros automaticamente.
Segurança e Escopo: As ações são executadas com segurança dentro dos limites do seu plano de usuário e credenciais.
Compatibilidade Universal com Clientes: Funciona em Claude Desktop, Cursor, Google Antigravity, VS Code, Windsurf, Zed, LibreChat e SDKs personalizados.
Consciência de Cota em Tempo Real: Agentes de IA inspecionam seus links restantes antes de criar links para evitar erros de cota.

Protocolo de Autenticação

O Servidor Surli MCP suporta dois caminhos de autenticação: OAuth 2.0 Nativo com 1 Clique (zero chaves de API necessárias) e Cabeçalhos de Chave de API (necessários para clientes sem OAuth).

[!warning] Aviso

Importante: Preciso de uma Chave de API?

Claude Desktop (OAuth Nativo): NENHUMA CHAVE DE API NECESSÁRIA. O Claude Desktop abre nativamente seu navegador para login OAuth com 1 clique. Você NÃO precisa configurar ou passar uma chave de API!

Google Antigravity, CLI Headless e Clientes sem OAuth: CHAVE DE API NECESSÁRIA. Serviços e IDEs que não suportam OAuth interativo no navegador DEVEM passar a chave de API da Surli nos cabeçalhos HTTP (Authorization e X-API-KEY).

1. OAuth 2.0 (Claude Desktop e Clientes de Navegador) Nenhuma Chave de API Necessária

Projetado para clientes de IA desktop como Claude Desktop que suportam autorização OAuth nativa RFC 8414. Nenhuma chave de API é necessária — basta fornecer a URL do endpoint, e seu cliente abre automaticamente uma aba do navegador para login com 1 clique.

URI do Endpoint	Descrição
`/.well-known/oauth-authorization-server`	Endpoint de descoberta RFC 8414.
`https://mcp.surl.li/oauth/authorize`	URL de autorização do navegador.
`https://mcp.surl.li/oauth/token`	Endpoint de troca de token.

2. Cabeçalhos de Chave de API (Antigravity e Sem OAuth) Chave de API Necessária

Necessário apenas para clientes sem suporte a OAuth no navegador (como Google Antigravity, Windsurf, Zed, daemons CLI e SDKs programáticos).

Cabeçalhos HTTP Necessários:

Authorization: Bearer YOUR_API_KEY

X-API-KEY: YOUR_API_KEY

Trecho de configuração:

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

Passar ambos os cabeçalhos Authorization e X-API-KEY garante autenticação imediata em clientes headless e proxies.

Endpoints e Protocolo de Transporte

O Servidor Surli MCP suporta autenticação por Chave de API (Authorization e X-API-KEY) e Autorização OAuth 2.0 juntamente com transportes padrão de streaming HTTP JSON-RPC e Server-Sent Events (SSE).

Endpoint	Método	Tipo / Protocolo	Descrição
`https://mcp.surl.li/mcp`	GET / POST	Endpoint MCP Unificado	Endpoint MCP primário de produção com suporte a Chave de API (`Authorization` e `X-API-KEY`) e autenticação OAuth 2.0.
`https://mcp.surl.li/oauth/authorize`	GET	Autorização OAuth 2.0	Fluxo de login no navegador para autorização de token OAuth 2.0 do cliente de IA.
`https://mcp.surl.li/oauth/token`	POST	Token OAuth 2.0	Troca o código OAuth/token de atualização por credenciais de acesso MCP.
`https://mcp.surl.li/mcp/sse`	GET	SSE (Server-Sent Events)	Endpoint de sessão de transporte SSE com streaming.
`https://mcp.surl.li/mcp/messages`	POST	HTTP JSON-RPC 2.0	Lida com mensagens RPC brutas `initialize`, `tools/list` e `tools/call`.

Configurações de Cliente de IA (11+ Clientes de IA Suportados)

O Servidor Surli MCP suporta dois caminhos de autenticação: OAuth 2.0 Nativo com 1 Clique e Cabeçalhos de Chave de API.

Quando uma Chave de API é necessária vs. NÃO necessária?

Claude Desktop: NENHUMA Chave de API Necessária!

Claude Desktop suporta OAuth nativo no navegador com 1 clique. Você NÃO precisa passar ou configurar nenhuma chave de API! Basta fornecer a URL https://mcp.surl.li/mcp e autenticar com 1 clique no seu navegador.

Antigravity e Sem OAuth: Chave de API Estritamente Necessária

Clientes e IDEs que não possuem OAuth no navegador (como Google Antigravity, Windsurf, Zed, scripts CLI e SDKs) DEVEM passar a chave de API da Surli em headers (Authorization e X-API-KEY) usando serverUrl.

Localização do arquivo: %APPDATA%\Claude\claude_desktop_config.json (Windows) ou ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

[!success] Sucesso Zero Chaves de API Necessárias: O Claude Desktop conecta-se nativamente via OAuth 2.0. Você NÃO precisa passar nenhuma chave de API! Basta adicionar a URL do endpoint, e o Claude abrirá automaticamente seu navegador para login:

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

Nota headless/teste: Uma chave de API só é necessária se você estiver executando em um ambiente headless sem acesso ao navegador; nesse caso, você pode passar "headers": { "Authorization": "Bearer YOUR_API_KEY", "X-API-KEY": "YOUR_API_KEY" }.

O Cursor suporta tanto OAuth nativo quanto configuração direta de chave de API:

Opção A: OAuth com 1 Clique (Nenhuma Chave de API Necessária)

Em Configurações do Cursor → Recursos → Servidores MCP, adicione um novo servidor com tipo SSE / OAuth e URL https://mcp.surl.li/mcp, ou adicione a .cursor/mcp.json:

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

Opção B: Cabeçalhos Diretos de Chave de API

Se não estiver usando OAuth, configure sua chave de API da Surli em headers:

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

Nas configurações do VS Code Roo Code (mcp_settings.json), adicione a configuração do servidor Surli MCP:

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

Edite cline_mcp_settings.json:

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

Edite ~/.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

Edite ~/.continue/config.json em 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

Edite ~/.config/zed/settings.json em 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

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

Adicione ao seu librechat.yaml em mcpServers:

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

[!warning] Aviso Chave de API Estritamente Necessária: O Antigravity não suporta login OAuth interativo no navegador. Você DEVE fornecer sua Chave de API da Surli em headers (ambos Authorization e X-API-KEY) com serverUrl.

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

Passar ambos os cabeçalhos Authorization: Bearer YOUR_API_KEY e X-API-KEY: YOUR_API_KEY garante que o Antigravity conecte e autentique na inicialização.

SDKs Programáticos

SDK Python (pacote 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 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);

Exemplos de Uso e Prompts de IA

Depois que o Servidor Surli MCP estiver habilitado em seu agente de IA, você pode conversar com sua IA em linguagem natural. O agente de IA chamará automaticamente a ferramenta Surli MCP apropriada.

Prompt: Encurtar Links

"Ei, por favor, encurte este link de destino https://github.com/hypermans/dev-surli com o alias personalizado 'dev-surli' e o título 'Dev Surli Repo'."

[!secondary] Secundário Ação da IA: Chama create_short_link(destination_url='...', alias='dev-surli', title='Dev Surli Repo') e exibe o resultado.

Prompt: Verificar Cota da Conta

"Quantos links curtos ainda tenho na minha conta Surli para este mês?"

[!secondary] Secundário Ação da IA: Chama get_account_limits() e relata o nível do plano, a quantidade usada e a cota restante.

Prompt: Atualizar Destino do Link

"Altere o destino do link 'dev-surli' para apontar para https://surl.li/docs em vez disso."

[!secondary] Secundário Ação da IA: Chama update_destination(surl='dev-surli', new_destination_url='https://surl.li/docs').

Prompt: Alterar Alias

"Atualize o alias do link 'dev-surli' para 'surli-api'."

[!secondary] Secundário Ação da IA: Chama update_alias(surl='dev-surli', new_alias='surli-api').