@webpinch/mcp

Expõe tarefas, projetos, auditorias de site e estatísticas do WebPinch como ferramentas/recursos/prompts MCP para Claude Code, Cursor e outros clientes MCP.

Ver em webpinch.comExperimente este MCPPatrocinado

Documentação

O WebPinch inclui um servidor MCP (@webpinch/mcp) que expõe suas tarefas, projetos, auditorias de site e estatísticas para o Claude Code, Cursor e qualquer outro cliente MCP.

É um cliente leve sobre a API REST — mesma autenticação, mesma autorização, mesmos dados de resposta. Onde a API REST fornece endpoints HTTP brutos, o MCP fornece ferramentas que o modelo pode chamar diretamente.

O que você obtém

13 ferramentas para ler e escrever tarefas, projetos, auditorias e estatísticas
4 recursos para dados navegáveis e mencionáveis (projetos, tarefas, relatórios de auditoria)
3 prompts para fluxos de trabalho comuns (triagem, resumo de auditoria, status semanal)
Verificações de escopo pré-voo para que tentativas de escrita falhem rapidamente com uma mensagem clara em vez de um HTTP 403

Instalação

Você precisará de:

Um token de acesso pessoal do WebPinch. Crie em Dashboard → API Tokens.
Node 18+ na máquina que executa o cliente MCP.

Edite ~/.claude.json e adicione (ou mescle com) seu bloco mcpServers:

{
  "mcpServers": {
    "webpinch": {
      "command": "npx",
      "args": ["-y", "@webpinch/mcp"],
      "env": {
        "WEBPINCH_TOKEN": "wp_pat_...",
        "WEBPINCH_API_URL": "https://www.webpinch.com"
      }
    }
  }
}

Reinicie completamente o Claude Code (saia, não apenas feche a janela). Execute /mcp — webpinch deve aparecer listado como conectado com 13 ferramentas, 4 recursos, 3 prompts.

Desenvolvimento local? Substitua WEBPINCH_API_URL por http://localhost:3000. Se você estiver executando o servidor MCP a partir de um checkout (ainda não publicado no npm), troque command / args por node /absolute/path/to/mcp-server/src/index.js.

Variáveis de ambiente

Var	Padrão	Observações
`WEBPINCH_TOKEN`	(obrigatório)	Seu token `wp_pat_…`
`WEBPINCH_API_URL`	`https://www.webpinch.com`	URL base da instância WebPinch
`WEBPINCH_TRANSPORT`	`stdio`	Defina como `http` para auto-hospedar via Streamable HTTP — veja Transporte HTTP hospedado
`PORT`	`8787`	Usado apenas quando `WEBPINCH_TRANSPORT=http`

O token é lido na inicialização do servidor e nunca é registrado em log ou ecoado na saída das ferramentas. Erros de rede o redigem explicitamente.

Ferramentas

Leitura

Ferramenta	Argumentos	Retorna
`whoami`	—	Usuário, nome do token + escopos, organizações e projetos acessíveis
`list_projects`	`orgSlug?`	Lista de projetos, opcionalmente limitada a uma organização
`get_project`	`projectId`	Detalhes do projeto, incluindo colunas + membros
`list_tasks`	`projectId?`, `status?`, `priority?`, `assigneeId?`, `label?`, `q?`, `limit?`, `page?`	Lista compacta de tarefas
`get_task`	`taskId`	Tarefa completa, incluindo comentários, listas de verificação, anexos, captura de tela/pin
`list_audits`	`projectId?` ou `orgSlug?`, `limit?`	Resumos de auditoria
`get_audit`	`auditId`	Relatório completo de auditoria
`dashboard_stats`	`orgSlug?`	Contagens por status/prioridade, projetos recentes

Escrita

Ferramenta	Argumentos	Escopo
`create_task`	`projectId`, `title`, `description?`, `priority?`, `status?`, `labels?`, `assigneeIds?`, `pageUrl?`, `dueDate?`	`tasks:write`
`update_task`	`taskId`, qualquer um de `title` / `description` / `status` / `priority` / `assigneeIds` / `labels` / `dueDate` / `dueDateComplete`	`tasks:write`
`comment_on_task`	`taskId`, `body`	`tasks:write`
`start_audit`	`projectId`, `maxDepth?`, `maxPages?`	`audits:run`
`reanalyze_audit`	`auditId`	`audits:run`

A saída é podada para eficiência de tokens. Ferramentas de listagem nunca incluem descriptionHtml ou logs de atividade completos — chame a ferramenta get_* correspondente quando precisar de detalhes.

Pré-voo de escopo

Ferramentas de escrita buscam seus escopos uma vez via whoami e os armazenam em cache. Se você pedir ao modelo para fazer algo que seu token não pode, a ferramenta lança um erro antes de qualquer requisição HTTP:

Esta ação requer o escopo "tasks:write". Seu token não o possui. Crie um novo token com esse escopo em /dashboard/settings/api.

A aplicação de escopo no lado do servidor ainda é executada como fonte da verdade — o pré-voo é puramente uma otimização de UX para dar ao modelo uma mensagem de erro útil em vez de um HTTP 403 opaco.

Recursos

Recursos são URIs que o modelo pode puxar sem você nomear uma ferramenta. No seletor de recursos do Claude Code / menção @ do Cursor:

URI	Tipo	Conteúdo
`webpinch://projects`	JSON	Todos os projetos acessíveis
`webpinch://projects/{projectId}/tasks`	JSON	Lista de tarefas de um projeto
`webpinch://tasks/{taskId}`	JSON	Detalhe de uma única tarefa
`webpinch://audits/{auditId}/report.md`	Markdown	Auditoria renderizada como relatório Markdown — seções para Crawl, Links, SEO, verificações gerais

O relatório de auditoria em Markdown é a maneira mais amigável de alimentar resultados de auditoria em um chat — é pré-formatado, priorizado e curto.

Prompts

Prompts são instruções salvas que compõem ferramentas. Eles aparecem como comandos de barra ou seleções de prompt no seu cliente.

triage_new_tasks

Argumentos: projectId?, sinceHours? (padrão 24).

Puxa tarefas criadas nas últimas N horas, percorre cada uma para contexto (descrição, captura de tela, relator) e propõe prioridade + responsável + uma justificativa de uma frase como tabela markdown. Não altera nada — revise antes de aplicar.

summarize_audit

Argumentos: projectId.

Busca a auditoria mais recente do projeto, categoriza descobertas (Crítico / Alto / Médio / Baixo) e escreve uma lista de correções com URLs afetadas e correções de uma frase. Termina com uma seção "Top 3 ações para esta semana".

weekly_status

Argumentos: orgSlug?.

Puxa estatísticas e atividade recente, redige uma nota de status de < 200 palavras em Markdown — o que há de novo, o que está em risco, progresso por projeto, o que está por vencer.

Transporte HTTP hospedado

A especificação MCP suporta ambos os transportes stdio (processo por cliente) e Streamable HTTP (hospedado). O WebPinch executa ambos, e eles expõem as mesmas ferramentas, recursos e prompts — escolha o que seu cliente suportar.

Use o nosso (sem instalação)

O WebPinch hospeda um endpoint MCP em https://www.webpinch.com/api/mcp. Nada para instalar e nada para manter em execução — útil para clientes que aceitam uma URL MCP remota, como os conectores Claude.ai e ChatGPT.

{
  "mcpServers": {
    "webpinch": {
      "url": "https://www.webpinch.com/api/mcp",
      "headers": { "Authorization": "Bearer wp_pat_..." }
    }
  }
}

A autenticação é por requisição via cabeçalho Authorization em vez de uma variável de ambiente, então o mesmo endpoint atende a todos os usuários — o token decide o que você pode ver. O endpoint é sem estado e habilitado para CORS.

Um GET retorna um pequeno documento de descoberta, que é uma maneira rápida de confirmar a acessibilidade:

curl https://www.webpinch.com/api/mcp
# {"ok":true,"name":"webpinch-mcp","version":"0.2.1","transport":"http","endpoint":"/api/mcp"}

Auto-hospede

Se você preferir executá-lo dentro da sua própria rede, o mesmo servidor fala HTTP:

WEBPINCH_TRANSPORT=http PORT=8787 WEBPINCH_TOKEN=wp_pat_... npx -y @webpinch/mcp

Ele escuta em POST /mcp (e /v1/mcp para compatibilidade).

stdio continua sendo o padrão certo para editores locais — Claude Code, Cursor e Windsurf todos iniciam o processo por conta própria, então não há nada para hospedar e o token permanece na sua configuração local.

Solução de problemas

Sintoma	Causa provável
Servidor mostra "desconectado" em `/mcp`	O comando de inicialização falhou. Execute `npx -y @webpinch/mcp` manualmente com as mesmas variáveis de ambiente — a mensagem de erro é o bug.
`WEBPINCH_TOKEN is required`	A variável de ambiente não está sendo passada pelo cliente MCP. Verifique o bloco `env` na sua configuração — variáveis de ambiente do seu shell NÃO são herdadas.
`INSUFFICIENT_SCOPE` após o pré-voo passar	O cache `whoami` está desatualizado porque você recriou o token no meio da sessão. Reinicie completamente o cliente MCP.
`Project has no URL configured` em `start_audit`	Defina a URL do projeto em `Dashboard → Project Settings`.
Ferramentas de leitura funcionam, mas tudo está vazio	O token é válido, mas não herda acesso a nenhum projeto. Execute `whoami` para verificar o que está visível.

Veja também

Última atualização em