Servidor MCP do Elido para Claude Desktop, Cursor e Code

O servidor MCP do Elido é um pequeno processo Node que permite ao Claude Desktop, ao Cursor ou ao Claude Code criar links curtos, listá-los e ler séries temporais de cliques de dentro de um chat. Ele vive no monorepo em packages/mcp-server, fala MCP por stdio e conversa com a mesma API REST que todo o resto.

Uma correção logo de início, porque uma versão anterior deste guia errou: o pacote não está no npm e ainda não é público. Em 2026-11-11, npm view @elido/mcp-server retorna 404; um lançamento público vem em breve. Até lá, você o executa a partir de uma compilação local. Tudo abaixo foi conferido com o código em packages/mcp-server e services/api-core.

O que é o MCP

O Model Context Protocol é um padrão aberto para permitir que um cliente de IA chame ferramentas que vivem fora do modelo. O cliente inicia um servidor ou se conecta a ele, pede a lista de ferramentas e envia as chamadas de ferramenta como mensagens JSON-RPC. O servidor faz o trabalho e devolve um texto que o modelo lê. O modelo nunca guarda a sua chave de API; quem guarda é o servidor.

A especificação define dois transportes, stdio para processos locais e Streamable HTTP para remotos (especificação do MCP, revisão mais recente de 2026-07-28, acesso em 2026-10-25). O servidor do Elido implementa apenas stdio.

O que o servidor faz

Ele é escrito à mão, sem o @modelcontextprotocol/sdk oficial, para não ter dependências. Em src/index.ts ele responde a quatro coisas: initialize (informando a versão de protocolo 2024-11-05), tools/list, tools/call e a notificação notifications/initialized. Qualquer outra coisa recebe um erro de "method not found". Não há handlers de resources, prompts nem ping.

Cada chamada de ferramenta vira uma requisição REST autenticada para ELIDO_API_BASE (padrão https://api.elido.app) com Authorization: Bearer <key> e o cabeçalho User-Agent: elido-mcp-server/0.1.0. As chamadas que falham voltam como um erro que inclui o status HTTP e os primeiros 400 caracteres da resposta.

Sobre o generate_qr: o api-core serve um POST /v1/qr/generate público e um design por link em GET /v1/workspaces/{id}/links/{link_id}/qr, mas nada no caminho que a ferramenta chama. Até isso ser reconciliado, eu não construiria um fluxo de trabalho em cima dela. Está no backlog.

Compile e Obtenha uma Chave de API

O monorepo é privado, então os passos abaixo valem quando você tiver o código-fonte do pacote (um lançamento público vem em breve). Compile o pacote:

pnpm install
pnpm --filter @elido/mcp-server build

Isso produz packages/mcp-server/dist/index.js. Você precisa do Node 20 ou mais novo (engines no package.json dele).

Para a chave, abra Dashboard, depois API keys (/dashboard/api-keys), dê à chave o nome do agente e escolha um papel. O formulário oferece viewer, editor e admin, com editor como padrão. As chaves do Elido carregam um papel de workspace, não escopos por ferramenta. Uma chave viewer é a opção somente leitura: ela pode listar e ler análises, e a API recusa create_link. Defina uma validade se a chave for para um período de teste. Copie a chave quando ela for exibida e mantenha-a fora do controle de versão.

Configure o Claude Desktop

O Claude Desktop lê o claude_desktop_config.json. O local da configuração e a aba de configurações Developer estão descritos na documentação do MCP (conectar servidores locais, acesso em 2026-10-25). No macOS o arquivo é ~/Library/Application Support/Claude/claude_desktop_config.json, e no Windows %APPDATA%\Claude\claude_desktop_config.json.

{
  "mcpServers": {
    "elido": {
      "command": "node",
      "args": [
        "/absolute/path/to/url-shortener/packages/mcp-server/dist/index.js"
      ],
      "env": {
        "ELIDO_API_KEY": "elido_your_key_here",
        "ELIDO_WORKSPACE_ID": "42"
      }
    }
  }
}

Use um caminho absoluto. ELIDO_WORKSPACE_ID só é opcional quando a chave enxerga exatamente um workspace; o servidor então chama GET /v1/workspaces uma vez e guarda o id em cache. Com dois ou mais workspaces ele lança um erro pedindo que você defina a variável, então defina-a desde o início.

Reinicie o Claude Desktop depois de salvar. Se o servidor não aparecer, execute primeiro o mesmo comando em um terminal. Uma chave ausente não interrompe o processo, ele imprime um aviso no stderr e todas as chamadas de ferramenta passam a falhar.

Configure o Cursor e o Claude Code

O Cursor lê o mesmo formato mcpServers de .cursor/mcp.json em um projeto, ou de ~/.cursor/mcp.json para todos os projetos (documentação de MCP do Cursor, acesso em 2026-10-25). Cole o bloco acima, adicione o arquivo ao .gitignore porque ele guarda uma chave ativa e confira o servidor nas configurações de MCP do Cursor.

O Claude Code adiciona um servidor stdio pela linha de comando (documentação de MCP do Claude Code, acesso em 2026-10-25):

claude mcp add --env ELIDO_API_KEY=elido_your_key_here --env ELIDO_WORKSPACE_ID=42 \
  --transport stdio elido -- node /absolute/path/to/packages/mcp-server/dist/index.js

Chaves em um arquivo de configuração ficam em texto simples. Em uma máquina compartilhada, dê a cada pessoa a sua própria chave para que a trilha de auditoria signifique alguma coisa.

Duas Sessões, com os Formatos Reais de Requisição

São conversas ilustrativas, não gravações, e os números são inventados. Os argumentos das ferramentas e os campos de resultado correspondem ao código.

Encurtar um link de campanha. Você pede ao Claude para encurtar https://shop.example.com/spring com o slug spring e a tag spring. Ele chama create_link com destination_url, slug, title e tags. Como nenhum domain_id foi passado, o servidor primeiro busca GET /v1/workspaces/{id}/domains e usa o primeiro retornado. Se o seu workspace tem vários domínios, passe o domain_id você mesmo. A API responde com o registro do link incluindo short_url, e o Claude coloca isso no rascunho. Se o slug já estiver em uso, a API retorna 409 "slug already exists for this domain", e o Claude pode escolher outro.

Ler os cliques da semana passada. Você pede os cliques diários de um link, no horário de Berlim. O Claude chama query_analytics com link_id, from, to, interval: "day" e tz: "Europe/Berlin". As datas são YYYY-MM-DD, e a API rejeita um intervalo em que from não seja anterior a to, então passe o dia seguinte ao seu último dia como to. Se você as omitir, o intervalo são os últimos 30 dias. O resultado é {"items": [{"ts": "...", "count": 312}, ...]}. Não há campo total, então peça ao Claude que some as contagens. Apenas cliques: nenhum detalhamento por país, dispositivo ou referenciador passa por essa ferramenta.

Segurança e Limites

Papéis, não escopos. Escolha o menor papel que resolve o trabalho. Viewer para agentes de relatório, editor para os que criam links, admin só com um motivo específico.

O que sai da sua máquina. O servidor envia requisições para a base da sua API do Elido e para nenhum outro lugar. O que o seu cliente de IA envia ao próprio provedor é coberto pela política desse provedor.

Trilha de auditoria. Criar uma chave emite um evento de auditoria api_key.created, e a criação de um link emite link.created. Não verifiquei como um evento é atribuído a uma chave individual, então não conte com o log de auditoria para distinguir dois agentes. Dê a cada um a sua própria chave e acompanhe a lista de chaves.

Limites de taxa. As chamadas contam no limite do workspace: 10 requisições por segundo no Free, 30 no Pro e 100 no Business, com folgas de rajada de 20, 60 e 200 (services/api-core/internal/httpserver/server.go). Um agente que cria centenas de links deve usar POST /v1/workspaces/{id}/links/bulk pela API, como em importação em massa a partir de uma planilha do Google.

MCP remoto. Seria um endpoint hospedado com OAuth, para que um conector do Claude pudesse alcançar o Elido sem um processo local. Ele está planejado, não construído, e o catálogo de integrações do painel lista apenas o servidor local. Use-o por enquanto.

Divergência de protocolo. O servidor declara 2024-11-05 enquanto a revisão atual da especificação é 2026-07-28. Não o testamos com todas as versões de clientes, então confira o status do servidor no seu cliente depois de uma atualização.

Para Onde Isso Vai

As lacunas acima estão no backlog: publicar o pacote, corrigir o generate_qr, adicionar Streamable HTTP e o endpoint remoto, adicionar mais ferramentas (atualizar, apagar, detalhamentos geográficos) e atribuição de auditoria por chave. Para um caminho diferente até a mesma ideia de agente, veja o guia do Gemini e o guia do ChatGPT; para a higiene de chaves, permissões de chaves de API para ferramentas de links.

Relacionados no Blog

• Permissões de chaves de API para ferramentas de links - papéis, privilégio mínimo e rotação.

• Importe links curtos em massa a partir de uma planilha do Google - o caminho certo para centenas de links.

• Encurtador de URL com Gemini - onde as chamadas de ferramenta funcionam no Gemini.

• Encurtador de URL com ChatGPT - o que funciona e o que finge funcionar.

• Links curtos como Terraform - gestão de links no estilo de infraestrutura.

• Limites de taxa e idempotência de uma API de encurtador de URL - como os limites se comportam para os clientes.

• Marius