Primeiros passos com o MCP do Cortex

Público: um agente de código (Claude Code, Codex, Cursor) trabalhando para uma pessoa. Tudo aqui pode ser verificado pelo terminal; o único passo no navegador é a pessoa entrar.

1. Conectar

O servidor MCP de dev é https://mcp.dev.infra.doublex.ai/mcp: Streamable HTTP, com OAuth. No Claude Code:

claude mcp add --scope user --transport http cortex https://mcp.dev.infra.doublex.ai/mcp

O --scope user registra o servidor para todas as pastas. Uma entrada cortex de escopo local (o que o comando cria sem a flag) tem prioridade sobre a de escopo user; se você já adicionou errado, remova antes: claude mcp remove cortex -s local.

No primeiro uso o servidor responde 401 com WWW-Authenticate: Bearer resource_metadata=...; o cliente descobre o servidor de autorização por /.well-known/oauth-protected-resource e abre o navegador para a pessoa, que entra com a mesma conta do console.

Se o cortex aparecer sem ferramentas, ou continuar pedindo login: no Claude Code digite /mcp, escolha cortex e depois Authenticate.

Confira: chame whoami. Ele responde com a organização, o plano e os seus escopos.

O comando cortex. Ele não está no npm, e npx cortex instala outro pacote com o mesmo nome: nunca rode. Construa a partir do checkout da plataforma com make cli, que deixa o cortex em ~/.local/bin. Você precisa dele para o cortex deploy, não para falar com o MCP.

2. Autenticar o terminal

cortex login                       # abre o navegador; o emissor é descoberto pela API
cortex login --pat <token>         # CI, ou quando o navegador não abre
cortex whoami --json

A credencial é validada antes de ser gravada em ~/.cortex/credentials.json com modo 0600. CORTEX_TOKEN no ambiente vence o arquivo, então o CI nunca precisa de passo de login. Os tokens são criados na página Tokens do console.

3. As ferramentas

tools/list é sempre a verdade. Os grupos, com as ferramentas que você usa primeiro:

Grupo	Ferramentas
Conta	`whoami`, `list_projects`, `get_project`, `create_project`, `delete_project`
Fontes	`upload_file`, `finalize_upload`, `add_source`, `test_source`, `list_sources`, `remove_source`, `set_secret`
Pipelines	`run_pipeline`, `get_run`, `get_run_logs`, `list_runs`, `schedule_pipeline`, `cancel_run`
Exploração	`list_tables`, `describe_table`, `sample_table`, `profile_table`
Consulta	`run_sql`, `estimate_query`, `get_query_result`
Modelagem	`get_project_config`, `apply_project_config`, `propose_model`, `run_models`, `list_models`, `get_change_set`, `list_change_sets`, `approve_change_set`, `reject_change_set`
Semântica e IA	`get_semantic_model`, `validate_semantic`, `query_metrics`, `explain_metric`, `ask`, `set_ai_provider`, `list_ai_providers`
App	`get_template`, `create_deployment`, `get_deployment`, `list_deployments`, `get_build_logs`, `get_app_logs`, `rollback_deployment`, `promote_deployment`, `set_env_var`, `list_env_vars`, `get_health`, `get_app_metrics`
Usuários finais	`invite_end_user`, `list_end_users`, `set_end_user_roles`, `set_end_user_attrs`, `disable_end_user`
Orçamento	`get_usage`, `get_budget`, `get_limits`, `set_spend_cap`

A maioria das ferramentas recebe um project_id (o ULID que o create_project devolve, não o slug). Publicar a partir de uma pasta é o cortex deploy, que empacota a pasta e chama o create_deployment por você.

4. Lendo um resultado

Todo resultado traz _meta["cortex/usage"] com cu_seconds, bytes_scanned, cost_estimate_usd e budget_remaining_usd. Acompanhe: custo é requisito, não relatório.

5. Lendo um erro

Os erros são estruturados, em inglês, e dizem o que fazer:

{ "error": { "code": "limit.bytes_exceeded", "message": "query would scan 12 GB",
             "hint": "Filter by order_date, or upgrade the plan.",
             "details": { "bytes_estimated": 12884901888 } } }

Códigos comuns: auth.unauthenticated, auth.scope_missing, validation.config_invalid, not_found, conflict.slug_taken, limit.bytes_exceeded, limit.spend_cap, approval.required, upstream.unavailable.

O CLI os converte em códigos de saída: 0 ok, 2 uso, 3 autenticação, 4 não encontrado, 5 conflito, 6 limite, 7 validação, 9 ainda não implementado, 1 qualquer outro.

6. Aprovações

Uma mudança num ambiente protegido nunca se aplica em silêncio. O approve_change_set pergunta à pessoa pelo MCP, com um resumo e um diff. Você espera a resposta; não contorna.

Próximos

O Início rápido vai do cadastro à URL publicada; Criar um projeto é o mesmo caminho com uma fonte de dados real.