Ir para o conteúdo
Promovaweb

O servidor MCP por projeto

O servidor MCP do ClickUpfy é o processo stdio que o cliente do agente inicia com clickupfy mcp, já com o perfil, o Space e a List do projeto fixados nos argumentos. Quando uma ferramenta recebe um ID diferente do fixado, o servidor recusa a chamada com isError, por isso o agente de um repositório não cria nem altera tarefa na List de outro projeto.

Ficha e sumário da página

Referência técnica
ClickUpfy v1.1.2
Revisão
13 de novembro de 2026
Conteúdo
Documentação oficial consultada
  1. Um processo que o cliente do agente inicia
  2. O escopo fixado
  3. Read-only na superfície do servidor
  4. Leitura em Markdown para o agente
  5. Conferir o que o cliente enxerga

Um processo que o cliente do agente inicia

O Model Context Protocol define como um cliente, como o Claude Code ou o Codex, descobre e chama ferramentas de um servidor externo. No ClickUpfy, esse servidor é o próprio binário rodando com o comando clickupfy mcp. O transporte é stdio: o cliente abre o processo, troca mensagens JSON-RPC pela entrada e pela saída padrão e encerra o processo junto com a sessão. Por isso a saída padrão fica reservada para essas mensagens, sem nenhum log do servidor no meio.

No uso diário, você não digita esse comando: o cliente MCP lê a entrada do servidor no arquivo de configuração do projeto e inicia o processo com os argumentos gravados ali. O comando clickupfy mcp setup, executado na raiz do repositório, pergunta o nome do servidor, os clientes, o perfil, o Space e a List. Depois ele grava a entrada no .mcp.json do Claude Code, no .codex/config.toml do Codex, no .gemini/settings.json do Gemini CLI e no opencode.json do OpenCode, cada um no formato do próprio cliente. O setup mescla a entrada nova com as que já existem, sem apagar outros servidores.

O escopo fixado

Cada entrada fixa até seis níveis da hierarquia do ClickUp nos argumentos do processo. A List é obrigatória, porque ela define o destino das consultas, das buscas e das tarefas criadas. Os níveis acima dela e o Sprint Folder entram quando o projeto precisa deles.

  • --account promovawebO perfil local, com a API key no cofre do usuário.
  • --workspace <id>O workspace do ClickUp associado a esse perfil.
  • --space <id>O Space do projeto, escolhido no setup.
  • --folder <id>O Folder, quando a List fica dentro de um.
  • --list <id>A List do projeto: destino obrigatório de buscas e criações.
  • --sprint-folder <id>O Sprint Folder, quando o projeto usa Sprints.
Os níveis que o servidor MCP compara em cada chamada, do perfil local ao Sprint Folder. A List é obrigatória. Os demais níveis entram quando o projeto precisa fixá-los.

O isolamento atua de dois jeitos: quando uma ferramenta omite um ID, o servidor usa o valor fixado. Quando a ferramenta recebe um ID diferente do fixado, o servidor recusa a chamada com isError: true, a mensagem e o exit code equivalente da CLI. A busca de tarefas também fica dentro da List do projeto. Com isso, dois clientes MCP abertos em repositórios diferentes trabalham ao mesmo tempo sem cruzar destino.

As ferramentas de Docs ficam fora dessa comparação, porque um Doc do ClickUp pertence ao workspace, fora de qualquer List. Elas operam no workspace do perfil resolvido, sem conferir Space, Folder ou List.

Read-only na superfície do servidor

Com a opção --read-only, o servidor não registra as ferramentas de escrita. Elas somem da resposta de tools/list, então o agente nem enxerga a ferramenta que cria ou altera uma tarefa. Como a restrição fica no servidor, uma instrução ignorada pelo agente não abre caminho para alterar a tarefa. A documentação recomenda esse modo para descoberta, auditoria, demonstração e qualquer conversa que não autorize alterações. O percurso do primeiro projeto instala o MCP em read-only para conferir o destino e só então libera a escrita.

  • 23 de leituraPerfil, hierarquia, tarefas, comentários, tags, Sprints, cronômetro e Docs, disponíveis também em read-only.
  • 22 de escritaCriação e atualização de tarefas, tags, checklists, comentários, Sprints, tempo e páginas de Doc.
  • 173 da APICada operação das APIs v2 e v3 vira uma ferramenta clickupfy_api, só as de leitura em read-only.

A ferramenta clickupfy_mcp_context mostra ao agente o perfil e os IDs fixados, sem expor a API key. A ferramenta clickupfy_list_get devolve os status válidos da List, que as skills usam para escolher o status final de uma tarefa. As ferramentas destrutivas, como clickupfy_task_delete e clickupfy_tag_delete, só executam com confirm: true no argumento.

Ao lado das ferramentas do ClickUp, o binário traz ferramentas próprias de diagnóstico, como doctor, exit_codes e credentials_status, que não devolvem o valor de nenhuma credencial. O servidor também publica três resources fixos, com a identidade do binário, a tabela de exit codes e a documentação completa em Markdown, mais um template que entrega uma seção da documentação por tópico. Ele oferece ainda um prompt chamado operate, que instrui o agente a ler a referência da CLI e executar uma tarefa por ela com --json.

Leitura em Markdown para o agente

A ferramenta clickupfy_task_get aceita markdown: true. Nesse modo, a resposta chega como um texto único, com metadados, descrição, resumo e checkboxes hierárquicos, em vez de um documento JSON escapado dentro de uma string. O agente gasta menos espaço no contexto do modelo com aspas e quebras de linha escapadas e lê a hierarquia de subtarefas e checklists na própria indentação.

Conferir o que o cliente enxerga

O comando clickupfy mcp --list descreve as ferramentas, os resources e os prompts sem iniciar o servidor. Com --json, a mesma lista sai estruturada. Para chamar as ferramentas à mão e ver as mensagens JSON-RPC, a documentação usa o MCP Inspector, que abre uma página local ligada ao processo. Quando o cliente não lista nenhuma ferramenta, a página do servidor MCP segue a conexão do comando local até o recarregamento do cliente, com o clickupfy doctor no meio do caminho.

O servidor usa o perfil e o cofre descritos na página Perfis, workspaces e cofre. As skills que chamam essas ferramentas numa ordem definida estão na página Skills dos agentes.

StayCloud

Uma VPS para desenvolver com agentes

Servidor da StayCloud em São Paulo, com acesso root e disco NVMe, para deixar seus agentes de IA rodando o dia todo.

Montar minha VPS

Link de parceiro da Promovaweb.