Agentes e MCP
O MCP é um protocolo que permite que um agente de IA use ferramentas externas. Ao conectar um agente ao fazer.ai projects, você pode pedir que ele leia e altere projetos, tarefas, comentários, anexos, lembretes, revisões e notificações. As operações seguem as mesmas regras da interface do produto.
Agentes
Um agente é um tipo de usuário que sempre pertence a uma pessoa. Você já tem um agente padrão com o nome Agente de <seu primeiro nome>. Em Configurações → Agentes, você pode criar outros, até o limite de 10 agentes por pessoa. Você pode usar um para o Claude Code no notebook e outro para uma automação no n8n, por exemplo.
O agente vê exatamente o que o dono vê. Quando ele cria algo ou publica um comentário, a ação aparece em nome do agente. A interface também mostra quem é o dono, então quem lê um comentário pode identificar qual agente escreveu e a quem ele pertence.
O endereço do servidor
O servidor MCP do fazer.ai projects usa o transporte Streamable HTTP e fica neste endereço.
https://projects.fazer.ai/api/mcpUse o login no navegador, via OAuth, quando estiver no computador e puder aprovar a conexão. Esse fluxo autentica o cliente sem guardar uma chave de API nele. Use uma chave de API do agente para scripts, automações, chamadas com claude -p ou servidores que rodam sem navegador.
Claude Code
Com login no navegador
Rode este comando para cadastrar o servidor projects no Claude Code.
claude mcp add --transport http -s user projects https://projects.fazer.ai/api/mcpA opção -s user deixa o servidor disponível em qualquer pasta. Sem essa opção, ele fica disponível só na pasta em que você rodou o comando. No Claude Code, rode /mcp e selecione projects. O navegador abre o fazer.ai projects. Entre na sua conta se precisar. Na tela Conectar ..., escolha a organização e selecione o agente em Agir como. Confira o que ele poderá fazer e clique em Aprovar.
Com uma chave de API
Rode os comandos abaixo no terminal em que você vai abrir o Claude Code. A primeira linha pede a chave sem mostrá-la na tela nem registrá-la no histórico do shell. Cole a chave e pressione Enter. Depois de registrar o servidor, abra o Claude Code nesse terminal para que ele receba PROJECTS_TOKEN. Se já estiver aberto, feche e abra de novo a partir do shell em que você exportou a variável.
read -rs PROJECTS_TOKEN && export PROJECTS_TOKEN
claude mcp add --transport http -s user projects https://projects.fazer.ai/api/mcp \
--header 'Authorization: Bearer ${PROJECTS_TOKEN}'Mantenha as aspas simples no valor de --header. Elas fazem o Claude Code guardar o texto ${PROJECTS_TOKEN} e ler a variável a cada conexão. Com aspas duplas, o shell substitui a variável pela chave antes de passar o valor ao Claude Code. Nesse caso, a chave fica em texto puro no arquivo ~/.claude.json.
Codex
Com login no navegador
Use os comandos abaixo para cadastrar o servidor no Codex e, quando precisar, refazer o login.
codex mcp add projects --url https://projects.fazer.ai/api/mcp
codex mcp login projectsO primeiro comando registra projects e já abre o login no navegador. Use codex mcp login projects se a janela não abrir ou se você precisar entrar novamente. Na tela de aprovação, escolha a organização e o agente em Agir como, confira o que ele poderá fazer e clique em Aprovar.
Com uma chave de API
No terminal, rode os comandos abaixo, cole a chave quando a primeira linha pedir e pressione Enter.
read -rs PROJECTS_TOKEN && export PROJECTS_TOKEN
codex mcp add projects --url https://projects.fazer.ai/api/mcp --bearer-token-env-var PROJECTS_TOKENO Codex grava só o nome da variável em ~/.codex/config.toml e lê a chave do ambiente a cada uso.
[mcp_servers.projects]
url = "https://projects.fazer.ai/api/mcp"
bearer_token_env_var = "PROJECTS_TOKEN"Outros agentes compatíveis com MCP
No Cursor, no Windsurf, no VS Code, no n8n ou em outro cliente que fale MCP por HTTP, configure o endereço do servidor e escolha a autenticação. Se o cliente aceitar OAuth, ele descobre onde iniciar o login na resposta HTTP 401 do primeiro acesso e se registra automaticamente. Em um cliente sem OAuth, envie a chave no cabeçalho Authorization: Bearer <chave>. Vários clientes usam um arquivo de configuração com este formato.
{
"mcpServers": {
"projects": {
"type": "http",
"url": "https://projects.fazer.ai/api/mcp",
"headers": { "Authorization": "Bearer ${PROJECTS_TOKEN}" }
}
}
}Se o cliente não expandir ${PROJECTS_TOKEN}, escreva a chave no lugar da variável e mantenha o arquivo fora do Git e de pastas sincronizadas.
Conferir a conexão
No Codex, codex mcp list mostra o servidor com Bearer token quando você configura a autenticação por chave. Para testar a conexão em qualquer cliente, peça ao agente “chame o whoami do projects”. A resposta traz o handle do agente, o dono, a organização, os escopos e a data de hoje no fuso configurado. Se a chamada devolver esses dados, a conexão está funcionando.
Chaves de API
Abra Configurações → Agentes, selecione o agente que vai usar a conexão e clique em Criar chave. Escolha os escopos conforme as ações que ele precisa executar e defina uma expiração se quiser. Para um agente que consulta e atualiza informações no dia a dia, selecione read e write.
readpermite ver tarefas, projetos e pessoas.writepermite criar e alterar.adminpermite agir como administrador. Só o dono ou um admin da organização pode usar esse escopo. Uma chave comadminexpira em até 7 dias.
A chave começa com fzp_ e aparece uma única vez, na hora da criação. Guarde o valor em um gerenciador de senhas e use o valor guardado ali para exportar PROJECTS_TOKEN. A criação e a revogação de chaves, inclusive da própria chave em uso, só podem ser feitas pela interface.
Desconectar e revogar
Abra Configurações → Agentes. Em Apps conectados, você encontra os clientes que entraram pelo navegador e pode usar Desconectar para encerrar o acesso de um deles. Para interromper na hora todas as conexões que usam uma chave, clique em Revogar ao lado dela. A revogação é definitiva. Desativar o agente interrompe o acesso por todas as chaves dele e desconecta seus apps.
O que o agente pode fazer
Você pode pedir ao agente que consulte as informações do projeto e faça alterações dentro das permissões do dono e dos escopos da conexão. Toda operação de escrita aceita uma chave de idempotência. Se o cliente repetir a mesma chamada com a mesma chave de idempotência, o servidor devolve o resultado da primeira chamada sem gravar a alteração de novo.
Apagar uma tarefa ou um anexo, arquivar, juntar ou apagar um projeto e apagar uma label ou um workflow exigem confirmação explícita. O cliente deve perguntar antes de enviar essa confirmação. Uma tarefa apagada vai para a lixeira e pode ser restaurada por 30 dias. Para um anexo apagado, o prazo é de 7 dias. Apagar de vez da lixeira, juntar projetos e apagar um projeto são ações irreversíveis.
Problemas comuns
- Erro HTTP 401. A chave pode ter expirado ou sido revogada, ou o agente pode estar desativado. Confira também se
PROJECTS_TOKENestava definida quando o cliente abriu. Se você exportou a variável depois, feche o cliente e abra de novo a partir do shell que tem a variável. - Erro
forbidden. A chave não tem o escopo que a ação exige. Uma tentativa de escrita com uma chave que tem sóread, por exemplo, precisa de uma chave comwrite. - Erro
request_budget_exceededou HTTP 429. Os agentes de uma mesma pessoa passaram de 500 chamadas por minuto, somando API e MCP. A resposta indica quantos segundos esperar antes de tentar novamente. - O login abre, mas a tela de aprovação não mostra nenhum agente. Crie um em Configurações → Agentes ou use Novo agente na própria tela de aprovação.
- Você quer conectar uma instância no seu servidor. Quando a versão self-host estiver disponível, substitua
https://projects.fazer.aipelo endereço da sua instância em todos os comandos.