Pular para o conteúdo
LinkProfit

Servidor MCP para assistentes de IA

Conecte Claude Code, Claude Desktop ou Cursor ao seu espaço de trabalho pelo Model Context Protocol: configurações prontas, catálogo de ferramentas, permissões e planos.

Atualizado em 14 de agosto de 2026

O servidor MCP permite que um assistente de IA trabalhe diretamente com os seus links e o seu analytics: “encurte esta landing page no nosso domínio de marca”, “quais foram os cinco links com mais cliques na semana passada”, “silencie a regra de alerta do domínio da campanha até segunda-feira”. O assistente faz isso pela mesma API pública que você mesmo chamaria, com exatamente os direitos da chave com que você o conectou.

https://api.linkprofit.com/v1/mcp

O transporte é JSON-RPC 2.0 sobre HTTP, seguindo a revisão 2025-06-18 do Model Context Protocol (a revisão 2025-03-26 também é aceita). Não há fluxo de eventos iniciado pelo servidor nem estado de sessão: GET e DELETE respondem 405, nenhum Mcp-Session-Id é emitido, e cada requisição carrega na própria chave todo o contexto de que precisa. Qualquer cliente MCP que fale HTTP funciona — os três abaixo são apenas aqueles para os quais entregamos configurações prontas para copiar e colar.

1. Crie uma chave para o assistente

No seu painel, abra Configurações → Chaves de API e crie uma chave de espaço de trabalho (lp_live_…). Conceda a ela apenas os escopos que o assistente realmente deve ter — o catálogo de ferramentas abaixo indica o que cada ferramenta exige. Uma chave com links:read + analytics:read dá a você um assistente somente leitura, que responde perguntas mas não muda nada.

O valor completo da chave é exibido uma única vez. Trate-o como uma senha: ele vai parar em um arquivo de configuração na sua máquina.

2. Adicione o servidor ao seu cliente

Claude Code

Um comando, sem arquivo de configuração para editar:

claude mcp add --transport http linkprofit https://api.linkprofit.com/v1/mcp \
  --header "Authorization: Bearer lp_live_…your key…"

Acrescente --scope user para deixar o servidor disponível em todos os projetos da sua máquina, e não só no atual. Confira o resultado com claude mcp list e remova-o depois com claude mcp remove linkprofit.

Claude Desktop

Edite o arquivo de configuração — no macOS, ~/Library/Application Support/Claude/claude_desktop_config.json; no Windows, %APPDATA%\Claude\claude_desktop_config.json — e acrescente o servidor:

{
  "mcpServers": {
    "linkprofit": {
      "type": "http",
      "url": "https://api.linkprofit.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer lp_live_…your key…"
      }
    }
  }
}

Reinicie o Claude Desktop. As ferramentas aparecem no seletor de ferramentas de uma nova conversa.

Cursor

Crie .cursor/mcp.json no projeto (ou ~/.cursor/mcp.json para tê-lo em todo lugar):

{
  "mcpServers": {
    "linkprofit": {
      "url": "https://api.linkprofit.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer lp_live_…your key…"
      }
    }
  }
}

O Cursor lê o arquivo ao salvar e mostra o servidor em Settings → MCP.

Verificar a conexão na mão

Os problemas de qualquer cliente são mais fáceis de ler no nível do protocolo. Este é o mesmo handshake que os clientes executam:

curl -s -X POST https://api.linkprofit.com/v1/mcp \
  -H "Authorization: Bearer $LINKPROFIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "curl", "version": "1.0" }
    }
  }'

Uma resposta saudável informa a versão do protocolo, o servidor e a sua capacidade de ferramentas. Troque o método por tools/list para ver o catálogo, e por ping para verificar nada além da acessibilidade.

Ferramentas

Dez ferramentas, todas restritas ao espaço de trabalho ao qual a chave pertence. A coluna de escopo indica o que a chave precisa carregar; uma ferramenta para a qual a chave não tem escopo simplesmente falha quando é chamada — ela não fica escondida do catálogo.

| Ferramenta | O que faz | Escopo necessário | | --- | --- | --- | | list_links | Lista os links curtos do espaço de trabalho, opcionalmente filtrados por um texto de busca | links:read | | get_link | Lê um link pelo seu id | links:read | | create_link | Cria um link curto; sem domain_id, é usado o domínio padrão do espaço de trabalho | links:write | | update_link | Altera o destino ou o título de um link existente | links:write | | analytics_summary | Cliques, visitantes e leituras de QR de um período, opcionalmente de um único link | analytics:read | | analytics_breakdown | Cliques e visitantes agrupados por país, cidade, dispositivo, navegador, sistema operacional, referer ou UTM | analytics:read | | analytics_top_links | Os links mais clicados do período, com cliques e visitantes | analytics:read | | analytics_timeseries | Cliques e visitantes ao longo do tempo, por hora, dia ou semana | analytics:read | | list_alert_rules | Lista as regras de alerta com os seus canais e a janela de supressão | alerts:read | | update_alert_rule | Ativa, desativa ou reajusta a janela de supressão de uma regra de alerta | alerts:write |

Os esquemas de argumentos vêm das mesmas definições que validam a chamada, então o que se diz ao assistente sobre uma ferramenta e o que o servidor de fato aceita não conseguem se afastar. As ferramentas somente leitura são anotadas como tal, e é isso que permite a um cliente pedir confirmação antes das três ferramentas que alteram dados: create_link, update_link e update_alert_rule — mais o que uma versão futura acrescentar a essa lista.

Toda chamada de ferramenta que altera dados é registrada na trilha de auditoria do espaço de trabalho, com a chave que a fez e a observação de que ela chegou por MCP, então as alterações de um assistente são tão rastreáveis quanto as de uma pessoa.

Permissões e segurança

A chave é a fronteira das permissões. Não existe um “modo assistente” privilegiado: uma chamada de ferramenta roda com os escopos da chave, dentro do espaço de trabalho da chave, sob o mesmo limite de requisições e o mesmo isolamento de tenant de uma chamada REST. Um id de outro espaço de trabalho é not_found, exatamente como pelo REST.

Três hábitos que vale adotar:

  • Dê ao assistente uma chave própria, nunca a que a sua integração de produção usa. Revogá-la depois não custa nada.
  • Comece com somente leitura. links:read + analytics:read cobre as perguntas de relatório que as pessoas de fato fazem a um assistente. Acrescente links:write só quando quiser links criados a partir do chat.
  • Faça a rotação em caso de exposição. Uma chave em um arquivo de configuração viaja junto com backups, compartilhamentos de tela e tíquetes de suporte. Revogue-a no painel no instante em que ela vazar; a requisição seguinte responde 401.

O limite de requisições é compartilhado com a API REST — por chave, em janela deslizante de um minuto —, então um assistente tagarela e um job em segundo plano na mesma chave disputam o mesmo orçamento. Esse é mais um argumento para uma chave separada. Veja Limites de requisições para os cabeçalhos e as regras de novas tentativas.

Requisitos de plano

Dois recursos de plano controlam o acesso ao endpoint:

  • api_access — o direito de usar a API, para começar;
  • assistant_tools — o direito de usar o catálogo de ferramentas e, portanto, o MCP.

Os dois são definidos no plano em que o seu espaço de trabalho está. Um espaço de trabalho cujo plano não tenha algum deles recebe 403 com o código plan_restricted e uma mensagem que nomeia a capacidade ausente. Se você revende o LinkProfit sob a sua própria marca, esse é um recurso que você decide incluir em um plano ou vender como upgrade.

Solução de problemas

403 plan_restricted — o plano não inclui assistant_tools (nem api_access). Faça upgrade do plano; nada na chave nem na configuração do cliente resolve este caso.

401 unauthorized — o cabeçalho está ausente, malformado, ou a chave é desconhecida, foi revogada ou expirou. Os três casos são propositalmente indistinguíveis. Confira se o valor é a chave inteira, se ele vem prefixado com Bearer , e se o cliente realmente envia o cabeçalho — o handshake com curl acima responde isso em uma única requisição.

403 forbidden — foi usada uma chave de parceiro (lpp_live_…). O MCP é uma superfície de espaço de trabalho; crie uma chave de espaço de trabalho.

429 rate_limited — a chave esgotou a sua janela. A resposta carrega Retry-After; clientes que tentam de novo na hora só mantêm a chave bloqueada.

405 no GET — é esperado, não é um defeito. O servidor não oferece fluxo de eventos e não mantém sessão; um cliente que só fale o transporte baseado em SSE das revisões antigas não consegue se conectar.

Uma ferramenta responde com erro em vez de dados — duas coisas diferentes se parecem em uma transcrição de chat. Argumentos que não passam na validação voltam como um resultado de ferramenta marcado como erro, listando os campos problemáticos, e o assistente consegue se corrigir e tentar de novo. Um escopo ausente volta como erro de protocolo, com o código insufficient_scope e o escopo indicado: esse caso precisa de uma chave nova, não de outra tentativa.

Leitura relacionada