Conectar o Projectura ao seu agente de IA — tutorial por plataforma

Liga o conector MCP do Projectura (projetos, tarefas, releases, equipes, documentos) ao seu cliente de IA, com comandos exatos para colar. Há uma seção por plataforma — vá direto à sua.

Dois conceitos, e não são a mesma coisa:

MCP (o conector) — funciona em todas as plataformas. Expõe as ferramentas projectura_* (ex.: projectura_tasks_list, projectura_releases_create). Sem o MCP conectado, não há o que executar.
Skills (fluxos prontos) — SKILL.md é um padrão aberto, hoje suportado por Claude Code, Claude Desktop, Codex, Gemini CLI, opencode, Antigravity e outros. As 7 skills do Projectura funcionam em todos — só o método de instalação muda por cliente. Skills não substituem o conector: elas orquestram, chamando as tools projectura_*. Quem preferir não instalar skills usa o arquivo de contexto nativo (CLAUDE.md/AGENTS.md/GEMINI.md) + as tools direto.

Resumo por plataforma

Plataforma	MCP (conector)	Skills (fluxos prontos)
Claude Desktop	stdio: `.mcpb` one-click ou JSON `npx -y @projectura/mcp`	Customize → Skills → upload ZIP
Claude Code	HTTP nativo: `claude mcp add --transport http`	marketplace `odevmaismais/projectura-skills` (1 comando)
OpenAI Codex	stdio `codex mcp add … npx -y @projectura/mcp` ou HTTP (`config.toml`)	copiar p/ `~/.agents/skills` (ou `npx @projectura/skills`) · nativo: `AGENTS.md`
Google Antigravity	HTTP `serverUrl`+header (MCP Store → View raw config)	copiar p/ a pasta de skills · nativo: Rules + Workflows
CLIs (Gemini CLI, opencode…)	stdio `npx -y @projectura/mcp` ou HTTP url+header	`~/.agents/skills` (ou `npx @projectura/skills`) · nativo: `GEMINI.md`/`AGENTS.md`

Atalho universal de skills: npx @projectura/skills copia as 7 skills para ~/.claude/skills (Claude Code) e ~/.agents/skills (Codex, Gemini CLI, opencode e demais que adotam o padrão) — um comando cobre quase todos. Claude Desktop é a exceção: ele instala por upload de ZIP (abaixo).

Passo 0 — Gerar o token (comum a TODAS as plataformas)

Abra https://projectura-next.vercel.app e faça login.
Configurações → Integrações → Conector MCP.
Gerar token e copie o valor — começa com pj_….

Segredo. O pj_… aparece uma única vez. Trate como senha: nunca cole em chat nem comite em arquivo versionado. Onde possível, passe por variável de ambiente (PROJECTURA_TOKEN) em vez do literal. Nos comandos abaixo, troque pj_SEU_TOKEN pelo PAT real.

Endpoint (referência): https://projectura-next.vercel.app/api/mcp.

Claude Desktop

O Desktop só fala stdio, então o conector entra via shim (@projectura/mcp, ponte stdio→HTTP que lê o token de PROJECTURA_TOKEN).

1) Conectar o MCP

Opção A — .mcpb one-click (recomendada): baixe projectura.mcpb, abra no Desktop em Settings → Extensions e cole o PAT no campo "PAT do Projectura".
Opção B — JSON stdio: Settings → Developer → Edit Config (claude_desktop_config.json):

{
  "mcpServers": {
    "projectura": {
      "command": "npx",
      "args": ["-y", "@projectura/mcp"],
      "env": { "PROJECTURA_TOKEN": "pj_SEU_TOKEN" }
    }
  }
}

Reinicie o Desktop.

2) Skills

Conecte o MCP primeiro (skills só orquestram). No Desktop: Customize (sidebar) → Skills → + → Create skill → faça upload de um ZIP contendo a pasta da skill (com SKILL.md). Para as 7 do Projectura, zipe cada pasta skills/projectura-*/ (clone odevmaismais/projectura-skills) e suba uma a uma. Cada skill ganha um toggle on/off e vale em todas as conversas (chat, projects, Cowork).

3) Verificar

Reinicie e peça: "liste minhas tarefas no Projectura" → deve chamar projectura_tasks_list. Se pedir workspace, peça antes "liste meus workspaces no Projectura".

4) Gotchas

O diálogo "conector personalizado/remoto" do Desktop não tem campo de header Authorization — por isso o caminho é o .mcpb ou o JSON stdio, não a URL HTTP direta.
Modo JSON precisa de Node/npx no PATH.
Token inválido/vazio → server disconnected. Refaça em Integrações.

Claude Code (CLI / IDE)

Fala HTTP nativo — não precisa de npx nem .mcpb. Pré-requisito: Claude Code atualizado + Node 18+. Se /plugin não existir, atualize (npm i -g @anthropic-ai/claude-code@latest).

1) Conectar o MCP — uma linha (escopo `user` = todos os projetos)

claude mcp add --transport http projectura https://projectura-next.vercel.app/api/mcp \
  --header "Authorization: Bearer pj_SEU_TOKEN" -s user

Versionar sem o token literal (expande ${PROJECTURA_TOKEN} do ambiente):

claude mcp add-json projectura '{"type":"http","url":"https://projectura-next.vercel.app/api/mcp","headers":{"Authorization":"Bearer ${PROJECTURA_TOKEN}"}}' --scope user

(-s project grava .mcp.json no repo; -s local/omitir = só este projeto.)

2) Skills — marketplace (1 comando)

Conecte o MCP primeiro. Numa sessão do Claude Code:

/plugin marketplace add odevmaismais/projectura-skills
/plugin install projectura@projectura

As skills ficam namespaced (/projectura:<skill>); rode /help para vê-las. (Sem skills: basta o MCP e pedir em linguagem natural — o Claude acha e chama as tools sozinho; reforce convenções no CLAUDE.md.)

3) Verificar

Fora da sessão: claude mcp list mostra projectura Connected.
Dentro: /mcp mostra projectura com contagem de tools > 0. Teste: "liste minhas tarefas no Projectura".
As tools projectura_* aparecem deferred (carregadas sob demanda) — normal, não é erro.

4) Gotchas

Conecte o MCP antes das skills.
Header exatamente "Authorization: Bearer pj_…" (com Bearer + espaço); sem Bearer → 401.
Token inválido → marca FAILED (não cai pra OAuth) → refaça o pj_.
Skills não aparecem? reinicie a sessão; se persistir, limpe ~/.claude/plugins/cache e reinstale.
Não use .mcpb/npx @projectura/mcp aqui — são do Desktop (stdio).

OpenAI Codex CLI

Pré-requisito: Node 22+ e Codex (npm i -g @openai/codex).

1) Conectar o MCP

Opção A — stdio (recomendada), comando único:

codex mcp add projectura --env PROJECTURA_TOKEN=pj_SEU_TOKEN -- npx -y @projectura/mcp

Confira com codex mcp list. Pronto — sem editar arquivo.

Opção B — HTTP em ~/.codex/config.toml (exporte PROJECTURA_TOKEN antes):

[mcp_servers.projectura]
url = "https://projectura-next.vercel.app/api/mcp"
bearer_token_env_var = "PROJECTURA_TOKEN"

Se o HTTP nativo não conectar, ative experimental_use_rmcp_client = true no topo do config.toml.

2) Skills

O Codex lê SKILL.md de ~/.agents/skills/ (global) e .agents/skills/ (por-repo) — não de .claude/skills nem .codex/skills. Atalho:

npx @projectura/skills      # copia as 7 skills p/ ~/.claude/skills E ~/.agents/skills

(Manual: git clone https://github.com/odevmaismais/projectura-skills && cp -r projectura-skills/skills/projectura-* ~/.agents/skills/.) Equivalente nativo (sem skills): AGENTS.md (~/.codex/AGENTS.md global + AGENTS.md no repo) com instruções de uso das tools projectura_*.

3) Verificar

codex mcp list lista projectura; no TUI, /mcp. Teste: "liste minhas tarefas no Projectura".

4) Gotchas

stdio: token via --env PROJECTURA_TOKEN=…; HTTP: bearer_token_env_var é o nome da variável (exporte antes), nunca o pj_ cru.
Windows: após setx PROJECTURA_TOKEN …, reabra o terminal.
1ª execução do npx baixa o pacote (Node 22+ e internet).

Google Antigravity (IDE + CLI)

1) Conectar o MCP

No IDE: abra um Agent → menu "…" → MCP Servers (abre a MCP Store) → Manage MCP Servers → View raw config. Isso abre o mcp_config.json (o caminho varia por versão — costuma ser ~/.gemini/antigravity/mcp_config.json ou ~/.gemini/config/mcp_config.json; use o "View raw config" e não se preocupe com o path). Adicione — HTTP, recomendado (usa serverUrl, não url, e sem comentários //):

{
  "mcpServers": {
    "projectura": {
      "serverUrl": "https://projectura-next.vercel.app/api/mcp",
      "headers": { "Authorization": "Bearer pj_SEU_TOKEN" }
    }
  }
}

Salve e dê refresh/toggle no server projectura na MCP Store. (Alternativa stdio: command: "npx", args: ["-y","@projectura/mcp"], env: { PROJECTURA_TOKEN } — requer Node.)

2) Skills

O Antigravity adota Agent Skills (SKILL.md). Sem marketplace de 1 clique: copie as pastas. Atalho npx @projectura/skills (instala em ~/.agents/skills, que o Antigravity também lê em vários setups) ou copie manualmente para a pasta de skills do seu Antigravity (global do IDE, da CLI, ou <proj>/.agents/skills). Nativo: Rules ("Always On", via AGENTS.md/GEMINI.md) + Workflows (slash commands).

3) Verificar

Na MCP Store, projectura aparece verde com as tools. Num chat de Agent: "liste minhas tarefas no Projectura". Skills: pergunte "quais skills do Projectura estão disponíveis?".

4) Gotchas

Use serverUrl, não httpUrl/url → senão fica disconnected.
JSON não aceita comentários inline (//) — quebra o parse.
Authorization com prefixo Bearer obrigatório.
Após editar, refresh/toggle na MCP Store (nem sempre há hot-reload).
O .mcpb e o plugin do Claude não se usam aqui.

CLIs (Gemini CLI, opencode e similares)

Conector por stdio (npx -y @projectura/mcp) ou HTTP (url + header). Skills via ~/.agents/skills (padrão aberto) ou o arquivo de contexto nativo.

Gemini CLI

# stdio (recomendado, -s user = global):
gemini mcp add -s user -e PROJECTURA_TOKEN=pj_SEU_TOKEN projectura npx -y @projectura/mcp
# ou HTTP:
gemini mcp add -s user --transport http projectura https://projectura-next.vercel.app/api/mcp -H "Authorization: Bearer pj_SEU_TOKEN"

Skills: npx @projectura/skills (→ ~/.agents/skills) ou o nativo GEMINI.md (~/.gemini/GEMINI.md global ou ./GEMINI.md; edite com /memory) ensinando a usar as tools projectura_*. Verifique com gemini mcp list.

opencode

Edite ~/.config/opencode/opencode.json (ou ./opencode.json), dentro de mcp:

"projectura": { "type": "local", "command": ["npx", "-y", "@projectura/mcp"], "enabled": true, "environment": { "PROJECTURA_TOKEN": "pj_SEU_TOKEN" } }

(HTTP: "type": "remote", "url": "…/api/mcp", "enabled": true, "headers": { "Authorization": "Bearer pj_SEU_TOKEN" }.) Skills: npx @projectura/skills (→ ~/.agents/skills) ou o nativo AGENTS.md.

Gotchas (CLIs)

Header HTTP exatamente Bearer pj_….
Expansão de env difere: Gemini CLI aceita $VAR/${VAR}; opencode usa environment (stdio) e {env:VAR} nos headers HTTP.
Gemini: gemini mcp add grava em ./.gemini/settings.json por padrão — use -s user para global.
Se o npm/npx @projectura/mcp falhar ou vier antigo, prefira a conexão HTTP direta (não depende do npm).

Catálogo das tools (prefixo `projectura_`)

Grupo	Tools
Contexto	`context`, `list_workspaces`
Projetos	`projects_list/get/create/update/delete/set_repos`
Tarefas	`tasks_list/get/create/update/move/delete/add_comment/log_time/add_subtask`
Releases	`releases_list/get/create/update/delete/link_task`
Equipes	`teams_list/get/create/update/delete/add_member/remove_member`
Documentos	`docs_list/get/create/update/delete`
Notificações	`notifications_list/unread_count`

Toda tool aceita workspace (id) para operar em outro workspace de que você é membro. Escritas em tarefas/docs/releases/comentários aparecem no app aberto em ~12s (polling); projetos/equipes aparecem no reload. Receitas de automação: guia de automação com IA.

Conectar o Projectura ao seu agente de IA — tutorial por plataforma

Resumo por plataforma

Passo 0 — Gerar o token (comum a TODAS as plataformas)

Claude Desktop

1) Conectar o MCP

2) Skills

3) Verificar

4) Gotchas

Claude Code (CLI / IDE)

1) Conectar o MCP — uma linha (escopo user = todos os projetos)

2) Skills — marketplace (1 comando)

3) Verificar

4) Gotchas

OpenAI Codex CLI

1) Conectar o MCP

2) Skills

3) Verificar

4) Gotchas

Google Antigravity (IDE + CLI)

1) Conectar o MCP

2) Skills

3) Verificar

4) Gotchas

CLIs (Gemini CLI, opencode e similares)

Gemini CLI

opencode

Gotchas (CLIs)

Catálogo das tools (prefixo projectura_)

1) Conectar o MCP — uma linha (escopo `user` = todos os projetos)

Catálogo das tools (prefixo `projectura_`)