Servidor MCP

O Bordio fala Model Context Protocol (MCP), então um assistente de IA lê e altera seu trabalho diretamente, em vez de você ficar copiando coisas de um lado para o outro.

https://api.bordio.com/mcp

A autenticação é OAuth: você aprova a conexão no navegador e não cola nenhuma chave. Chaves de API servem para integrações de servidor e não funcionam aqui.

Antes de começar

Três coisas determinam se a conexão vai funcionar. Confira primeiro: quase toda configuração que falha esbarra em uma delas, e não em um problema do cliente.

Um espaço de trabalho de equipe. Espaços pessoais não têm integrações em nenhum plano e não podem ser conectados.
Um plano pago ou um teste ativo. O teste funciona por completo e não exige cartão. No plano gratuito, ou depois que os pagamentos param, a conexão é criada mas cada chamada de ferramenta é recusada.
Ser membro, não convidado. Convidados não podem autorizar um aplicativo para o espaço de trabalho. Peça a um administrador para torná-lo membro.

As regras são verificadas em cada chamada, não apenas ao conectar — veja requisitos de plano e espaço de trabalho.

Conectar

Todos os clientes abaixo usam a mesma URL. Você nunca copia um token: o cliente abre o navegador, você entra no Bordio e aprova o acesso, e ele guarda o resultado.

Claude Desktop

Settings → Connectors → Add custom connector → cole a URL. Aprove na janela do navegador que abrir.

Claude Code

claude mcp add --transport http bordio https://api.bordio.com/mcp

Depois execute /mcp, escolha bordio e selecione Authenticate. Para entrar sem abrir uma sessão de trabalho, execute claude mcp login bordio.

Cursor

Adicione o servidor em ~/.cursor/mcp.json (disponível em todo lugar) ou em .cursor/mcp.json (só neste projeto):

{
  "mcpServers": {
    "bordio": {
      "url": "https://api.bordio.com/mcp"
    }
  }
}

O Cursor percebe a mudança e inicia o login pelo navegador no primeiro uso.

VS Code

Adicione o servidor em .vscode/mcp.json:

{
  "servers": {
    "bordio": {
      "type": "http",
      "url": "https://api.bordio.com/mcp"
    }
  }
}

Codex

codex mcp add bordio --url https://api.bordio.com/mcp
codex mcp login bordio

O login abre o navegador e guarda o resultado. O Codex se registra no Bordio na hora, então não é preciso obter um client id antes; se a sua versão perguntar como registrar, escolha o registro dinâmico (--oauth-client-registration dcr).

Versões antigas atendem servidores por URL com a pilha MCP anterior, onde o login por OAuth não roda. Se o login falhar ou o servidor não conectar, adicione isto ao ~/.codex/config.toml e tente de novo:

experimental_use_rmcp_client = true

O mesmo pelo arquivo, se preferir editá-lo direto:

[mcp_servers.bordio]
url = "https://api.bordio.com/mcp"

Outros assistentes

Qualquer um que aceite servidores MCP remotos por HTTP e consiga concluir o login OAuth — Windsurf, Zed e os demais — funciona igual: informe a URL e aprove no navegador.

Automações: use a API REST

n8n, Make, Zapier e seus próprios scripts são outro caso, e o MCP não é a ferramenta certa para eles.

Entrar aqui significa uma pessoa aprovando o acesso no navegador, e o token resultante pertence a ela. Uma automação que roda às três da manhã não tem quem abra um navegador, e não há como emitir para ela uma credencial MCP permanente: o Bordio não entrega credenciais de cliente OAuth para uso autosserviço.

Para automações, use a API REST com uma chave secreta: ela foi feita exatamente para isso — uma credencial de longa duração, sem navegador e sem validade para acompanhar. Tudo o que um assistente faz por MCP está disponível lá.

Criar seu próprio cliente MCP

Se você está escrevendo um cliente em vez de usar um pronto, não há nada para registrar à mão. O Bordio implementa a cadeia de descoberta definida pela especificação MCP, então um cliente compatível encontra tudo a partir da URL do endpoint:

Metadados do recurso protegido em /.well-known/oauth-protected-resource/mcp — apontam para o servidor de autorização;
Metadados do servidor de autorização em /.well-known/oauth-authorization-server — endpoints, permissões e métodos suportados;
Client ID Metadata Documents (o método que a especificação hoje prefere): publique um documento JSON descrevendo seu cliente e passe a URL HTTPS dele como client_id. Nós o buscamos, conferimos se o client_id de dentro coincide com a URL de onde veio e validamos suas redirect URIs contra ele;
Registro dinâmico de clientes em /oauth/register, como alternativa para clientes que não suportam o acima.

PKCE é obrigatório, apenas S256. URIs de retorno em loopback (http://127.0.0.1/... e http://localhost/...) são aceitas com qualquer porta, como os clientes nativos precisam.

Seja qual for o caminho, a tela de aprovação mostra à pessoa o domínio para onde o código de autorização vai voltar — é a única afirmação sobre o seu aplicativo que ela consegue verificar, então use um domínio reconhecível. Veja aprovar um aplicativo.

O que seu assistente pode fazer

Depois de conectado, pergunte em linguagem natural: «o que eu tenho hoje», «crie uma tarefa para renovar o certificado SSL, para sexta», «o que o time fechou na semana passada».

Área	O que o assistente pode fazer
Tarefas	Listar e filtrar, ler uma tarefa com subtarefas e comentários, criar, atualizar, fechar, excluir
Subtarefas	Listar, criar, atualizar, excluir
Eventos	Listar e ler eventos do calendário, criar e atualizar, gerenciar participantes
Lixeira	Ver o que foi excluído e restaurar uma tarefa ou evento — excluir não é definitivo
Agenda	Tudo dentro de um intervalo de datas — reuniões, prazos e trabalho planejado — em uma única lista ordenada
Resumo	Contagens de um período, por status e por responsável, sem listar cada registro
Comentários	Ler e escrever comentários em tarefas e eventos
Registro de tempo	Ler e registrar tempo trabalhado
Projetos, membros, etiquetas	Ler a estrutura do espaço de trabalho; arquivar e desarquivar projetos; gerenciar etiquetas
Definições	Status e tipos de tarefa, tipos de evento, status de projeto, campos personalizados

Tudo o que o assistente alcança pelo MCP, ele alcança com as suas permissões. Ele nunca verá um projeto que você não pode ver.

Nada do que ele faz aqui é permanente. Excluir uma tarefa ou um evento manda para a lixeira, de onde dá para restaurar por 30 dias; projetos são arquivados, não excluídos. Não existe ferramenta que destrua um registro de vez — veja excluir e restaurar.

Instruções prontas

O servidor traz três instruções prontas. No Claude Desktop elas aparecem como comandos para escolher, então você não precisa inventar a frase:

Instrução	O que faz
O que eu tenho hoje	Reuniões, prazos e trabalho planejado de hoje em uma lista ordenada, apontando o que merece atenção primeiro
Resolver o que está atrasado	Agrupa as tarefas vencidas e propõe uma nova data para cada uma: nada muda até você confirmar
Fechar minha semana	O que foi concluído, o que atrasou e o que espera na semana seguinte

Cada uma aceita um nome de projeto opcional para restringir.

Anexar um registro específico

Alguns clientes deixam anexar um recurso à conversa em vez de pedir que o assistente o procure. O Bordio expõe quatro:

bordio://workspace
bordio://project/{project_id}
bordio://task/{task_id}
bordio://event/{event_id}

Use quando você já sabe de qual registro se trata: o assistente trabalha direto com ele em vez de caçá-lo. As listas ficam do lado das ferramentas, onde moram filtros e paginação.

Permissões

A tela de aprovação mostra exatamente o que o aplicativo pede, e você concede as permissões por espaço de trabalho. Se você pertence a vários, escolhe um na aprovação: a conexão nunca vai além dele.

O assistente só enxerga as ferramentas cobertas pelas permissões: se a conexão foi aprovada só para leitura, as ferramentas de escrita não são recusadas — elas simplesmente não são oferecidas.

Permissão	O que cobre
`tasks:read` / `tasks:write`	Tarefas, subtarefas e seus comentários
`events:read` / `events:write`	Eventos de calendário, seus participantes e seus comentários
`projects:read` / `projects:write`	Projetos e sua configuração: status, tipos, campos personalizados
`time_logs:read` / `time_logs:write`	Tempo registrado
`tags:read` / `tags:write`	Etiquetas
`members:read`	Outras pessoas do espaço de trabalho, incluindo os e-mails
`profile:read`	Seu próprio nome e e-mail
`offline_access`	Continuar conectado sem perguntar de novo a cada hora

Vale pedir profile:read mesmo para um assistente somente leitura: sem isso nada responde «o que eu tenho hoje», porque o assistente não sabe qual dos membros do espaço de trabalho é você.

Um cliente que pede uma permissão que não pode ter não recebe erro: essa permissão é descartada, as demais são concedidas, e a tela de aprovação mostra o que de fato será dado. Leia a lista concedida na resposta do token em vez de supor que recebeu tudo o que pediu.

Você pode revisar e revogar conexões a qualquer momento em Perfil → Integrações → Aplicativos com acesso ao Bordio. A revogação vale imediatamente.

Requisitos de plano e espaço de trabalho

Conectar está aberto a qualquer pessoa: a tela de aprovação aparece para qualquer espaço de trabalho do qual você seja membro, em qualquer plano. O que o plano limita é usar a conexão: cada chamada de ferramenta é verificada, não só a primeira.

Situação	O que acontece
Espaço de equipe em um plano com integrações	Tudo funciona
Espaço de equipe em período de teste	Tudo funciona, sem cartão
Espaço de equipe onde um pagamento falhou mas o provedor ainda está tentando de novo	Continua funcionando: uma cobrança que não passou de primeira não é uma decisão de parar
Espaço de equipe no plano gratuito, ou depois que os pagamentos pararam de vez	A conexão continua, mas cada chamada devolve `workspace_plan_required` até o plano ser resolvido
Espaço pessoal	Não pode ser conectado: `integrations_unavailable`, em qualquer plano
Você é convidado no espaço de trabalho	Não pode autorizar um aplicativo para ele: `guest_access_denied`. Peça a um administrador para torná-lo membro

A verificação em cada chamada é proposital: uma aprovação concedida enquanto o plano estava ativo não continua valendo depois que ele expira. E o contrário também vale — assim que o plano volta, a conexão existente volta a funcionar sem reconectar nada.

Uma conexão cobre um espaço de trabalho. Você o escolhe na tela de aprovação, e a conexão nunca passa disso. Para trabalhar com outro, revogue a conexão em Perfil → Integrações → Aplicativos com acesso ao Bordio e autorize de novo escolhendo o outro.

Limites

Limite	Valor
Chamadas de ferramentas de leitura	180 / minuto
Chamadas de ferramentas de escrita	60 / minuto
Requisições ao endpoint, incluindo mensagens de protocolo	300 / minuto
Uma chamada de ferramenta	30 segundos
Uma resposta	128 KB

Mensagens de protocolo — conectar, listar ferramentas — não consomem o orçamento de chamadas. A leitura é mais generosa que na API REST porque uma pergunta costuma virar uma cadeia curta de chamadas.

Se uma resposta ultrapassar o limite de tamanho, a chamada é recusada com uma dica para restringir o pedido, em vez de ser cortada em silêncio: um assistente trabalhando com uma lista truncada tira conclusões de dados que ele não sabe estarem incompletos.

Quando algo não funciona

O que você vê	O que significa
O cliente pede autenticação repetidamente e a aprovação sempre dá certo	O token está sendo recusado depois de emitido. Confira em Perfil → Integrações → Aplicativos com acesso ao Bordio se a conexão não foi revogada ou bloqueada, depois remova o servidor no cliente e adicione de novo.
`workspace_plan_required` em toda chamada	O espaço está no plano gratuito ou os pagamentos pararam. A conexão está boa e volta assim que o plano voltar.
`integrations_unavailable`	O espaço que você aprovou é pessoal. Conecte um de equipe.
`guest_access_denied`	Você é convidado ali. Convidados não podem autorizar aplicativos: peça a um administrador para torná-lo membro.
`connection_blocked`	Um administrador interrompeu esta conexão. É reversível: peça para restaurá-la. Aprovar de novo não adianta enquanto o bloqueio existir.
O assistente diz que uma tarefa não existe e você a vê	A conexão age com as suas permissões e em um espaço de trabalho. Um registro de outro espaço, ou de um projeto do qual você não faz parte, está realmente fora do alcance dele.
Uma ferramenta de escrita não aparece	A conexão foi aprovada sem essa permissão. Revogue e aprove de novo concedendo-a.
As chamadas começam a falhar depois de uma rajada de atividade	Você atingiu o limite por minuto. O erro indica quanto esperar.

Aprovar um aplicativo

Qualquer aplicativo pode se conectar: o MCP permite que um aplicativo se registre sozinho, e nós não restringimos isso. Também não se concede nada às escondidas: o aplicativo recebe exatamente as permissões que a pessoa aprovou, e nada além.

O que a tela de aprovação mostra é o que realmente dá para conferir:

Mostrado	Por que é confiável
O nome e o logotipo do aplicativo	Enviados pelo próprio aplicativo, se o cliente se registrou sozinho, ou tirados do documento de metadados no seu domínio.
O domínio para onde o código volta	Não dá para falsificar sem controlar esse domínio. Para clientes de desktop e editores, a tela informa que o código volta para a máquina da própria pessoa.
A lista de permissões	Exatamente o que será concedido.

Não há fila de revisão nem pedido a enviar: um aplicativo que publica um documento de metadados no próprio domínio aparece sob esse domínio. Clientes conhecidos — Claude, Slack, Cursor, Codex e VS Code entre eles — ainda recebem de nós o nome e o logotipo, para serem reconhecidos de imediato.

Erros

O assistente recebe as falhas como respostas normais, então consegue se corrigir e tentar de novo: uma tarefa fora do alcance volta como «não encontrada», e não como servidor quebrado.

Situação	O que acontece
Sem sessão iniciada ou aprovação expirada	O cliente pede para autenticar de novo
Falta uma permissão ao aplicativo	A chamada é recusada e o cliente é informado de qual permissão falta
Limite de requisições atingido	A chamada é recusada informando quanto esperar
Registro não encontrado ou fora do seu acesso	O assistente é informado de que o registro não está disponível

Relacionado

Autenticação — chaves de API para integrações de servidor
Limites — limites da API REST
Erros — o catálogo completo de erros