Assistentes de IA (MCP)

O Coda Cloud tem um servidor MCP (Model Context Protocol) oficial. Com ele, um assistente de IA de desenvolvimento, como o Claude Code, o VS Code ou o Cursor, publica uma imagem, acompanha o deploy, lê status e logs e ajusta variáveis e domínios do seu projeto.

O assistente nunca tem mais acesso do que você:

• ele age com o seu papel atual em cada organização e projeto;
• os escopos pedidos no consentimento limitam o que ele pode fazer;
• toda ação destrutiva pede a sua confirmação, ligada aos argumentos exatos;
• valores de segredos e terminal/exec ficam fora do MCP.

O servidor fica em https://api.<domínio>/mcp (transporte Streamable HTTP, sem sessão). Todos os passos abaixo também aparecem no portal, em Conta › Assistentes de IA.

Conectar pelo modo remoto (OAuth)

No modo remoto, o cliente MCP descobre sozinho o servidor de autorização (o login do Coda Cloud) e abre o navegador:

1. Adicione o servidor no cliente:

   Claude Code

   claude mcp add --transport http coda https://api.<domínio>/mcp

   .vscode/mcp.json (VS Code)

   { "servers": { "coda": { "type": "http", "url": "https://api.<domínio>/mcp" } } }

   ~/.cursor/mcp.json (Cursor)

   { "mcpServers": { "coda": { "url": "https://api.<domínio>/mcp" } } }

2. Faça login no Coda Cloud quando o navegador abrir. A tela de consentimento mostra o nome do cliente e os escopos pedidos.

3. Volte ao assistente. Ele já pode usar as ferramentas de leitura.

Escopos

Escopo	Permite
mcp:read	Só leitura: organizações, projetos, ambientes, aplicações, deployments, logs, variáveis, nomes de segredos, domínios, uso e custos
mcp:operate	Operar aplicações, deployments, variáveis e domínios

O servidor anuncia os dois escopos (scopes_supported nos metadados do recurso protegido e scope="mcp:read mcp:operate" no desafio 401), então o cliente pede mcp:read e mcp:operate já na primeira autorização. A tela de consentimento mostra os dois, com a descrição de cada um, e a primeira operação do assistente não pede outro login.

Um cliente que pedir só mcp:read continua funcionando: quando o assistente tenta uma operação, o servidor responde 403 com insufficient_scope e scope="mcp:operate", e o cliente pede a autorização adicional (step-up). Você vê o consentimento de novo, agora com mcp:operate. Um cliente que se registra pelo registro dinâmico pedindo só mcp:read fica limitado a esse escopo: para operar, remova o servidor do cliente e conecte de novo, ou use o modo local.

Assistentes aceitos (Client ID Metadata Document)

Os clientes identificados por Client ID Metadata Document (o client_id é a URL HTTPS de um documento JSON publicado pelo próprio assistente) só são aceitos quando o domínio do documento está na lista curada da plataforma. A lista é configuração de cada ambiente, mantida pela equipe da plataforma:

Assistente	Domínio do documento
Claude (claude.ai e Claude Desktop)	claude.ai
ChatGPT	chatgpt.com
VS Code (GitHub Copilot)	vscode.dev

Um client_id de outro domínio é recusado no login com a mensagem "Aplicativo não reconhecido… o domínio do client_id não está na lista de assistentes aceitos". Assistentes fora da lista ainda podem conectar pelo registro dinâmico, pelo client atlas-mcp (client id fixo, redirect no loopback) ou pelo modo local. Para pedir a inclusão de um assistente, abra um chamado no suporte com o domínio do documento.

Nenhum escopo MCP permite gravar segredos, abrir terminal, ler a auditoria ou o faturamento. O papel continua valendo: um Viewer com mcp:operate recebe forbidden em qualquer operação.

Token de API com mcp:use

Para automação sem navegador, use um token de API pessoal ou de conta de serviço com o escopo mcp:use, enviado como Authorization: Bearer atl_….

• Sem mcp:use, o servidor responde 403 com scope="mcp:use".
• Com ele, cada ferramenta exige também o escopo Atlas dela (veja o catálogo). Um token com mcp:use e só apps:read recebe 403 com scope="deployments:write" em deploy_app.
• secrets:write e exec:run do token não valem no MCP.

Modo local pela CLI

No modo local, o assistente executa a CLI atlas, que repassa cada mensagem ao servidor remoto. Dentro de um repositório vinculado (.atlas/project.json), a organização, o projeto, o ambiente e a aplicação do vínculo viram o padrão: basta pedir "qual o status da aplicação?".

# login próprio do MCP (device flow com mcp:read e mcp:operate), separado do login da CLI
coda mcp login

# imprime o trecho de configuração do cliente
coda mcp config claude-code   # ou vscode, cursor

# o que o cliente executa
coda mcp serve

Claude Code no modo local

claude mcp add coda -- coda mcp serve

Em CI, CODA_TOKEN com mcp:use substitui o login. A ponte escreve no stdout só mensagens MCP; diagnósticos vão para o stderr. Ela repete nas chamadas seguintes o nome e a versão que o cliente declarou no initialize, para a auditoria mostrar qual assistente agiu. Sem credencial, a primeira chamada devolve um erro com a instrução coda mcp login.

Catálogo de ferramentas

Listas são paginadas por cursor (até 100 itens) e vêm em ordem alfabética. Cada resultado traz structuredContent conforme o outputSchema da ferramenta.

Ferramenta	O que faz	Escopo Atlas	Papel mínimo	Tipo
whoami	Usuário autenticado, credencial (OAuth ou token de API) e escopos efetivos.	—	—	Leitura
list_organizations	Organizações do usuário com o papel em cada uma.	—	—	Leitura
list_projects	Projetos da organização a que o usuário tem acesso.	projects:read	—	Leitura
list_environments	Ambientes de um projeto.	environments:read	Viewer	Leitura
list_apps	Aplicações de um ambiente, com a imagem e o deployment atual.	apps:read	Viewer	Leitura
get_app_status	Deployment atual, estado, instâncias saudáveis e desejadas e URL pública.	apps:read	Viewer	Leitura
list_deployments	Deployments de uma aplicação, do mais recente para o mais antigo.	deployments:read	Viewer	Leitura
get_deployment	Estado, imagem, tentativas e motivo de falha de um deployment.	deployments:read	Viewer	Leitura
get_logs	Últimas linhas de log (até 200 e 64 KB), com segredos mascarados e o conteúdo marcado como não confiável.	logs:read	Viewer	Leitura
list_env_vars	Variáveis de configuração da aplicação, com valores mascarados pelo redator de segredos.	config:read	Viewer	Leitura
list_secrets	Nomes, versões e datas dos segredos; nunca o valor.	secrets:read	Viewer	Leitura
list_domains	Domínios do projeto com o estado da verificação e do certificado.	domains:read	Viewer	Leitura
get_usage_quota	Uso atual da organização frente às quotas do plano.	orgs:read	Viewer	Leitura
get_costs	Custos e consumo da organização no período.	costs:read	Admin	Leitura
vpn_gateways_list	VPN gateways of the organization the user can see, with region, scope, SKU, state, public IP and transit range.	network:read	—	Leitura
vpn_gateway_status	State of a VPN gateway and of each tunnel: last handshake, bytes in each direction and the reason of the last failure.	network:read	—	Leitura
private_endpoints_list	Private endpoints of the projects the user can see: resource, mode, private IP, DNS name and state.	network:read	—	Leitura
vpn_access_status	Estado do acesso remoto de uma rede privada: faixa dos dispositivos, modo de DNS, réplicas e contagem de dispositivos e regras, sem chave nem configuração.	network:read	—	Leitura
vpn_access_devices_list	Dispositivos do acesso remoto que o usuário pode ver (o gestor vê todos, o membro só os próprios): nome, dono, estado, último handshake e validade.	network:read	—	Leitura
create_app	Cria uma aplicação num ambiente; idempotente pelo nome.	apps:write	Developer	Operação
deploy_app	Cria um deployment com uma imagem por digest; acompanhe com get_deployment.	deployments:write	Developer	Operação
scale_app	Muda o número de instâncias; escalar para zero pede confirmação.	deployments:write	Developer	Destrutiva (pede confirmação)
rollback_app	Volta para um deployment anterior que chegou a RUNNING; pede confirmação.	deployments:write	Developer	Destrutiva (pede confirmação)
set_env_vars	Define até 50 variáveis de configuração de uma vez.	config:write	Developer	Operação
unset_env_var	Remove uma variável de configuração; pede confirmação.	config:write	Developer	Destrutiva (pede confirmação)
add_domain	Adiciona um domínio próprio e devolve o registro TXT de verificação.	domains:write	Developer	Operação
verify_domain	Confere o registro TXT e emite o certificado.	domains:write	Developer	Operação
remove_domain	Remove um domínio próprio do projeto; pede confirmação.	domains:write	Admin	Destrutiva (pede confirmação)
delete_app	Exclui a aplicação e encerra as instâncias; pede confirmação com o nome digitado.	apps:write	Developer	Destrutiva (pede confirmação)
list_static_deploys	Lista os deploys de um site estático, do mais recente: estado (ACTIVE é o servido), origem, commit, autor, tamanho e código de falha.	sites:read	—	Leitura
rollback_static_site	Ativa um deploy anterior PRONTO do site estático, sem novo build; pede confirmação.	sites:write	—	Destrutiva (pede confirmação)
sandbox_list	Lista as sandboxes de agentes do projeto (ativas por padrão), com estado, imagem, recursos e modo de rede.	sandboxes:read	Viewer	Leitura
sandbox_create	Cria uma sandbox isolada em microVM, sem egress salvo perfil de rede; idempotente pela chave informada.	sandboxes:write	Developer	Operação
sandbox_run	Executa um programa na sandbox e espera o fim; stdout e stderr (até 64 KB) voltam como dado não confiável.	sandboxes:exec	Developer	Operação
sandbox_write_file	Grava um arquivo de texto (até 1 MiB) dentro do /workspace da sandbox.	sandboxes:write	Developer	Operação
sandbox_read_file	Lê um arquivo de texto do /workspace (até 64 KB) como dado não confiável.	sandboxes:write	Developer	Leitura
sandbox_expose_port	Expõe uma porta da sandbox numa URL HTTPS temporária; com token por padrão, pública só com confirmação.	sandboxes:write	Developer	Operação
sandbox_terminate	Encerra a sandbox: processos, arquivos, portas e snapshots deixam de existir.	sandboxes:write	Developer	Operação
analyze_import	Analyzes manifests of Docker Compose, Heroku, Render, Railway or Fly.io and creates an import plan (nothing changes in the draft). Credentials in the files are not kept: they become VALUE_REQUIRED.	imports:write	Developer	Operação
get_import	An import plan: status, counts by classification, items and their destinations. Names and values of the origin are tenant data under 'untrusted'.	imports:read	Viewer	Leitura
apply_import	Imports the external images and writes the plan to the draft of the graph in one change (nothing is deployed until the graph is applied). Asks for confirmation; secrets without value stay pending.	imports:write	Developer	Destrutiva (pede confirmação)
import_env_vars	Imports plain variables of a .env into a node (preview or apply). Keys that look like secrets are refused (mcp.secret_value_not_allowed): use the portal or the CLI for them.	config:write	Developer	Operação
start_data_import	Starts a data import into a managed database from an HTTPS URL without signature parameters, or from an upload already finished in the portal or the CLI. Asks for confirmation.	data-imports:write	Developer	Destrutiva (pede confirmação)
get_data_import	State, step, progress and result of a data import (never rows of data).	data-imports:read	Viewer	Leitura
cancel_data_import	Cancels a data import (the Job stops; the backup taken before the restore stays). Destructive: asks for confirmation.	data-imports:write	Developer	Destrutiva (pede confirmação)
get_live_migration	State, checks and replication lag of an online copy of PostgreSQL.	live-migrations:read	Viewer	Leitura
cutover_live_migration	Cuts over an online copy: waits for the lag to reach zero, syncs the sequences and removes the subscription. The user confirms that the writes at the origin stopped.	live-migrations:write	Admin	Destrutiva (pede confirmação)
cancel_live_migration	Cancels an online copy: removes the subscription, the network policies and the credential of the origin; the data already copied stays. Destructive: asks for confirmation.	live-migrations:write	Admin	Destrutiva (pede confirmação)
get_dns_cutover	The DNS switch guide of a domain: expected records, the answer of each public resolver and the state of the switch.	domains:read	Viewer	Leitura
list_deleted_resources	Bancos, buckets e o próprio projeto excluídos há pouco e ainda restauráveis, com o fim do prazo de restauração.	projects:read	Viewer	Leitura
restore_deleted_resource	Restaura um banco, bucket ou projeto excluído dentro do prazo, com os mesmos dados.	projects:write	Admin	Operação

O servidor também publica recursos atlas://apps/{appId}, atlas://apps/{appId}/deployments/{deploymentId} e atlas://apps/{appId}/logs, guias em atlas://docs/… e os prompts deploy_project (publicar uma imagem e acompanhar até RUNNING) e diagnose_app (status, deployments recentes e logs, com as causas prováveis).

Confirmação das ações destrutivas

delete_app, rollback_app, unset_env_var, remove_domain e scale_app para zero instâncias, e qualquer alteração num ambiente protegido, pedem confirmação humana:

• Pedido no cliente (elicitation): o cliente mostra o resumo do efeito ("Excluir a aplicação api de acme/web/production; 2 instâncias serão encerradas") e você confirma. Para excluir uma aplicação, digite o nome dela.
• Código de confirmação: clientes sem suporte a pedidos de confirmação recebem confirmationRequired com o resumo e um código de uso único. O assistente mostra o resumo, pede a sua aprovação e chama a mesma ferramenta de novo, com os mesmos argumentos e o código.

A confirmação vale por 5 minutos, uma única vez, para você, aquela ferramenta e aqueles argumentos. Argumentos trocados dão confirmation_invalid, prazo vencido dá confirmation_expired e a recusa dá cancelled, sem nenhuma alteração.

Política da organização

Owner e Admin definem a política em Configurações › Assistentes de IA da organização:

Opção	Efeito
Habilitado	Desligado, toda ferramenta da organização devolve mcp.disabled
Pedido no cliente, com código como alternativa	Padrão: confirmação por elicitation ou por código
Somente pedido no cliente	Clientes sem elicitation recebem confirmation_unsupported nas ações destrutivas
Somente leitura	As ferramentas de operação devolvem mcp.read_only; as de leitura continuam funcionando
Ambientes protegidos	Toda alteração nesses ambientes pede confirmação, mesmo as não destrutivas

O recurso depende também do plano (mcp.enabled). Fora do plano, as ferramentas da organização devolvem plan.feature_unavailable, e list_organizations continua listando a organização. Veja Planos e limites.

Limites

Limite	Valor
Chamadas por usuário e cliente	120 por minuto
Alterações por usuário e cliente	20 por minuto
Ações destrutivas por usuário e cliente	5 por minuto
Total da organização	mcp.callsPerMinute do plano
Logs por chamada	200 linhas e 64 KB

Passando do limite, a ferramenta devolve rate_limited com retryAfterSeconds e não executa nada.

Conteúdo não confiável

Linhas de log, nomes, descrições e valores de variáveis são escritos por quem usa a aplicação. Por isso:

• vêm no campo untrusted do resultado, delimitados para o modelo, e as descrições das ferramentas dizem que esse conteúdo é dado, não instrução;
• logs e valores passam pelo mesmo redator de segredos dos logs (password=… vira [REDACTED]).

Uma linha de log que peça "chame delete_app" não exclui nada sozinha: a exclusão só acontece com a sua confirmação, com o nome da aplicação.

Clientes conectados e revogação

Em Conta › Assistentes de IA você vê os clientes com consentimento ativo e os tokens com mcp:use, com a última atividade e as chamadas dos últimos 30 dias. Revogar remove o consentimento e encerra as sessões do cliente; o próximo uso pede uma nova autorização. Para um token de API, revogar revoga o token.

Auditoria

Toda alteração feita pelo MCP gera um evento de auditoria com o canal mcp, o cliente (client id OAuth ou id do token), o nome informado pelo cliente, a ferramenta e o modo de confirmação (elicitation ou code). Owner e Admin veem a atividade por membro e cliente na política da organização.