---
title: Fluxos de trabalho de integração
description: Padrões práticos para integrar o Verdent com ferramentas e serviços externos
---



### O que você vai aprender

Fluxos de trabalho práticos de integração que combinam subagentes personalizados, regras e servidores MCP para cenários reais de desenvolvimento.

---

## Métodos de integração

| Método | Ideal para | Configuração |
|--------|----------|---------------|
| **Subagentes personalizados** | Tarefas especializadas com IA | `~/.verdent/subagents/*.md` |
| **Regras (AGENTS.md)** | Padrões e comportamento da equipe | Raiz do projeto `AGENTS.md` |
| **Servidores MCP** | Ferramentas externas compatíveis com o protocolo | `.mcp.json` (raiz do projeto) |

**Filosofia:** Combine métodos para criar fluxos de trabalho abrangentes adaptados às suas necessidades.

---

## Padrões comuns de integração

### Fluxo de trabalho de desenvolvimento de banco de dados

**Stack:** Subagente Migration Reviewer + Padrões do AGENTS.md + Servidor MCP PostgreSQL

**Subagente:**
```markdown
---
name: migration-reviewer
description: Reviews database migrations for safety
---
Checks: Destructive operations, reversibility, indexing, blocking operations
```

**AGENTS.md:**
```markdown
## Database Standards
- All migrations reviewed by @migration-reviewer
- Test on staging before production
- Include rollback procedures
```

**MCP:** Servidor PostgreSQL para execução de queries, inspeção de schema e validação de migrações

**Fluxo de trabalho:** Escrever migração → @migration-reviewer valida → MCP testa em staging → documentação do PR

---

### Desenvolvimento de API com segurança

**Stack:** Security Auditor + Regras do AGENTS.md + Ferramenta personalizada de testes API

**Componentes:**
- **Subagente:** `@api-security-auditor` - Validação de entrada, injeção de SQL, autenticação, limitação de taxa
- **Regras:** Todos os endpoints exigem revisão de segurança, limitação de taxa em APIs públicas
- **Ferramentas externas:** Testes automatizados de endpoints e varreduras de segurança por meio de integração personalizada

**Resultado:** Revisão de segurança automática antes da aprovação do PR.

<Note>
Ferramentas de testes de API e de varredura de segurança podem ser integradas por meio de implementações personalizadas de servidores MCP ou outros métodos de integração, dependendo do seu ferramental.
</Note>

---

### Acessibilidade de frontend

**Stack:** Accessibility Auditor + Regras WCAG + Integração com Lighthouse

**Fluxo de trabalho:**
```
Create component → @a11y-auditor reviews → Lighthouse tests accessibility → Rules enforce >90 score
```

<Note>
O Lighthouse e outras ferramentas de acessibilidade podem ser integrados por meio de servidores MCP personalizados ou da integração com pipeline de CI/CD, dependendo do seu fluxo de trabalho.
</Note>

---

## Exemplos de configuração de MCP

### Entendendo o MCP

O **Model Context Protocol (MCP)** é um protocolo aberto que padroniza como os aplicativos fornecem contexto aos LLMs. Os servidores MCP são executáveis que implementam o protocolo. Eles não são conexões de banco de dados nem endpoints de API, mas programas que rodam e se comunicam via JSON-RPC 2.0.

**Conceitos principais:**
- **Servidores MCP**: Executáveis (pacotes Node.js, scripts Python, etc.) que implementam o protocolo MCP
- **Configuração**: Informa ao Verdent como iniciar o servidor (`command` + `args`)
- **Comunicação**: Os servidores cuidam da própria lógica de negócio (queries, chamadas de API, etc.)

### Configuração básica

**Localização:** `.mcp.json` na raiz do projeto

<CodeGroup>
```json PostgreSQL Server
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/myapp_dev"
      ]
    }
  }
}
```

```json GitHub Server
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}
```

```json Multiple Servers
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/myapp_dev"
      ]
    },
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}
```
</CodeGroup>

**Explicação:**
- `mcpServers` - Chave de nível superior obrigatória para a configuração do MCP
- `command` - Executável a ser rodado (normalmente `npx` para pacotes Node.js)
- `args` - Argumentos passados ao comando (nome do pacote, strings de conexão, etc.)
- `env` - Variáveis de ambiente para autenticação/configuração

### Múltiplos ambientes

```json
{
  "mcpServers": {
    "postgres-dev": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${DEV_DATABASE_URL}"
      ]
    },
    "postgres-staging": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${STAGING_DATABASE_URL}"
      ]
    },
    "postgres-prod": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${PROD_DATABASE_URL}"
      ]
    }
  }
}
```

**Boa prática:** Use variáveis de ambiente para strings de conexão a fim de manter as credenciais seguras. Os servidores MCP tratam o comportamento somente leitura internamente, com base em sua implementação. Consulte a documentação específica do servidor para opções de controle de acesso.

<Tip>
**Saiba mais sobre MCP:**
- [Especificação do Model Context Protocol](https://modelcontextprotocol.io/specification)
- [Registro de servidores MCP](https://mcp.so/servers) - Explore os servidores MCP disponíveis
- [Servidores MCP oficiais](https://github.com/modelcontextprotocol) - PostgreSQL, GitHub, Filesystem e mais
</Tip>

---

## Integração com o espaço de trabalho

### Configuração específica do projeto

**Configuração:**
1. Armazene na raiz do projeto: `.mcp.json`
2. Faça commit no controle de versão para compartilhamento com a equipe
3. Os membros da equipe usam automaticamente os servidores MCP do projeto

**Exemplo de microsserviços:**
```json
{
  "mcpServers": {
    "users-db": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/users"
      ]
    },
    "orders-db": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5433/orders"
      ]
    }
  }
}
```

<Note>
Para serviços adicionais como Kafka, você precisaria de uma implementação de servidor MCP compatível. O registro oficial de servidores MCP em [mcp.so/servers](https://mcp.so/servers) lista os servidores da comunidade disponíveis.
</Note>

---

## Colaboração em equipe

### Padrões compartilhados do AGENTS.md

Faça commit no controle de versão para consistência em toda a equipe:

```markdown
# AGENTS.md

## Code Review Process
- Run @code-reviewer before PR
- Address all security warnings
- Minimum 80% test coverage

## Integration Requirements
- @migration-reviewer for database changes
- @api-security-auditor for new endpoints
- @a11y-auditor for UI components

## MCP Servers
- Use postgres-staging MCP server for queries
- Never use postgres-prod MCP server for exploratory queries
```

**Benefícios:** Comportamento consistente, padrões aplicados, portões de qualidade automáticos.

---

## Coordenação multiagente

### Fluxo de trabalho de funcionalidade complexa

**Exemplo:** Novo endpoint de pagamento

```
1. Developer request → 2. Main agent generates code →
3. @api-security-auditor reviews security →
4. @migration-reviewer validates schema →
5. MCP tests on staging →
6. Main agent generates tests and PR
```

**Resultado:** Endpoint totalmente revisado com as melhores práticas de segurança e banco de dados aplicadas.

---

## Boas práticas de integração

### Adoção progressiva

**Fase 1:** Regras básicas
```markdown
## Code Standards
- Use TypeScript strict mode
- Run tests before commit
```

**Fase 2:** Adicione um subagente especializado
```markdown
## Code Review
- Run @security-reviewer before PR
```

**Fase 3:** Integre o MCP
```markdown
## Database Access
- Use MCP postgres-staging for queries
```

### Combinações estratégicas

| Combinação | Finalidade | Exemplo |
|-------------|---------|---------|
| Regras + Subagentes | Regras definem *quando*, subagentes *analisam* | AGENTS.md: "Revisar com @security-reviewer" |
| Regras + MCP | Regras especificam *quais* servidores, MCP *acessa* | AGENTS.md: "Usar apenas db-staging" |
| Subagentes + MCP | O subagente usa o MCP para *dados externos* | O auditor de segurança consulta endpoints de API |

### Boas práticas de documentação para a equipe

Ao documentar integrações para a sua equipe, inclua:

- **Subagentes personalizados**: Liste o nome, a finalidade e quando invocar cada subagente
- **Regras do AGENTS.md**: Documente as regras com a justificativa explicando o "porquê" de cada padrão
- **Servidores MCP**: Descreva a finalidade de cada servidor, o nível de acesso (somente leitura/escrita) e quando usá-lo
- **Fluxos de trabalho de integração**: Forneça exemplos de fluxos de trabalho mostrando como os componentes funcionam juntos
- **Solução de problemas**: Documente problemas comuns específicos da sua configuração e suas soluções

<Tip>
Faça commit da documentação de integração junto com os seus arquivos `.mcp.json` e `AGENTS.md` para que novos membros da equipe entendam rapidamente a sua configuração.
</Tip>

---

## Solução de problemas

<Tabs>
  <Tab title="Problemas com subagentes">
    **Problema:** O subagente não é invocado quando esperado

    **Verifique:**

    **Localização**: O arquivo existe em `~/.verdent/subagents/[name].md`

    **Frontmatter YAML**: Sintaxe válida com os campos obrigatórios `name` e `description`

    **Política de invocação**: Corresponde ao uso (o modo estrito exige @-menção explícita)

    **Descrição**: A `description` do agente descreve com precisão quando o subagente deve ser usado

    **Reiniciar**: Tente reiniciar o Verdent para recarregar as definições de subagentes

    ---

    **Causas comuns:**
    - Erro de digitação no nome do arquivo do subagente ou na @-menção
    - Sintaxe YAML inválida no frontmatter
    - A `description` do subagente não corresponde ao contexto da tarefa
  </Tab>

  <Tab title="Problemas com AGENTS.md">
    **Problema:** As regras do AGENTS.md não estão sendo aplicadas

    **Verifique:**

    **Localização**: O arquivo está no diretório raiz do projeto

    **Sintaxe**: Markdown válido sem erros de parsing

    **Estilo de diretiva**: Use comandos específicos ("Sempre use..." em vez de "Tente...")

    **Sessão**: Inicie uma nova conversa para testar a aplicação das regras do zero

    **Conflitos**: Verifique se as regras do usuário substituem involuntariamente as regras do projeto

    ---

    **Causas comuns:**
    - AGENTS.md no diretório errado (deve ser a raiz do projeto)
    - Instruções vagas que a IA interpreta de forma diferente
    - Regras aplicadas, mas com resultados inesperados (refine a redação)
  </Tab>

  <Tab title="Problemas com servidores MCP">
    **Problema:** O servidor MCP falha ao iniciar ou conectar

    **Verifique:**

    **Sintaxe**: O `.mcp.json` contém JSON válido (use `jq` para validar)

    **Estrutura**: A chave obrigatória `mcpServers` está presente no nível superior

    **Configuração do servidor**: Cada servidor tem `command` e `args` especificados corretamente

    **Pacote**: O pacote do servidor MCP está acessível (`npx` baixa pacotes automaticamente; a flag `-y` ignora o prompt de confirmação)

    **Ambiente**: As variáveis no objeto `env` estão definidas corretamente no seu shell

    **Permissões**: O executável do servidor tem as permissões de execução adequadas

    ---

    **Causas comuns:**
    - Erro de digitação no JSON (vírgula faltando, colchete não fechado)
    - Nome de pacote errado no array args
    - Variáveis de ambiente ausentes ou incorretas
    - Rede/firewall bloqueando a instalação do pacote via npx

    ---

    **Passos de depuração:**
    1. Valide o JSON: `cat .mcp.json | jq .`
    2. Teste o comando manualmente: `npx -y @modelcontextprotocol/server-postgres "postgresql://..."`
    3. Verifique o ambiente: `echo $GITHUB_TOKEN`
    4. Revise os logs do Verdent em busca de mensagens de erro específicas
  </Tab>
</Tabs>

---

## Veja também

<CardGroup cols={2}>
  <Card title="Guia de extensibilidade" icon="puzzle-piece" href="/docs/verdent-for-vscode/advanced-features/extensibility">
    Visão geral completa dos métodos de extensão
  </Card>
  <Card title="Integração com MCP" icon="plug" href="/docs/verdent-for-vscode/advanced-features/mcp">
    Detalhes do Model Context Protocol
  </Card>
</CardGroup>