# MCP

URL: /desenvolvedores/mcp

Conecte o Claude Code e o Codex aos reports do Mira pelo servidor MCP.

Agentes como o Claude Code e o Codex leem os reports **A fazer** e registram o andamento pelo MCP. Cada pessoa cria o próprio token de agente e adiciona a URL do Mira ao agente. Não há nada a instalar além do agente.

A URL do servidor é a do dashboard seguida de `/mcp`: `https://app.miraqa.org/mcp`.

Para scripts, ou para um agente que deve fazer tudo o que a pessoa faz na API, use a [CLI](/desenvolvedores/cli).

## Criar o token de agente [#criar-o-token-de-agente]

<Steps>
<Step>

### Abrir Conectar agente [#abrir-conectar-agente]

Clique no seu nome, no rodapé da barra lateral, e escolha **Conectar agente**. O diálogo tem duas colunas: à esquerda, o formulário do novo token. À direita, **Seus tokens** lista os tokens de agente da sua conta.

<Figure src="/images/agent-connect.png" alt="Diálogo Conectar agente com o formulário à esquerda e a lista Seus tokens à direita" caption="O diálogo Conectar agente." />

Para gerenciar os tokens com mais espaço, abra **Tokens de agente**, em **Configurações do Mira**. A tela lista o que cada token pode fazer, o último uso e a validade.

</Step>
<Step>

### Criar o token [#criar-o-token]

Preencha o formulário:

- **Nome do token**, para reconhecer o token na lista, como `notebook - claude code`.
- **Validade**: 30, 90 (padrão) ou 365 dias, ou **Sem validade**.
- **O agente lê**: **Screenshot**, **Console**, **Rede** e **Erros**. Todas começam marcadas.
- **O agente pode**: **Comentar**, **Alterar reports** e usar o selo "via agente" nos comentários. Todas começam marcadas. O selo só vale quando o agente pode comentar.

Clique em **Gerar comando**.

</Step>
<Step>

### Copiar o comando [#copiar-o-comando]

O formulário dá lugar ao comando de configuração, com as abas **Claude Code** e **Codex**. O token completo (`mira_pat_...`) já está no comando e aparece só nessa janela. Copie e clique em **Concluir**. Se fechar sem copiar, revogue o token e crie outro. Para configurar outro computador, abra **Configurar no cliente**, na página **Tokens de agente**; os comandos trazem `mira_pat_...` no lugar do token.

</Step>
</Steps>

<Callout type="warning" title="O token só serve no /mcp">
Ele tem o mesmo prefixo de um token pessoal, mas a API, a extensão, o widget e a CLI o recusam. O `/mcp`, por sua vez, recusa tokens pessoais e credenciais de serviço.
</Callout>

## Configurar o agente [#configurar-o-agente]

<Tabs items={["Claude Code", "Codex"]}>
<Tab value="Claude Code">

O escopo `user` deixa o Mira disponível em qualquer repositório:

```bash
claude mcp add --transport http --scope user mira https://app.miraqa.org/mcp --header "Authorization: Bearer mira_pat_..."
```

Confira com `claude mcp list` ou com `/mcp` dentro de uma sessão.

</Tab>
<Tab value="Codex">

O Codex lê o token de uma variável de ambiente. Coloque o `export` no perfil do shell, como `~/.zshrc` ou `~/.bashrc`, porque a variável precisa existir sempre que o Codex iniciar:

```bash
export MIRA_MCP_TOKEN="mira_pat_..."
codex mcp add mira --url https://app.miraqa.org/mcp --bearer-token-env-var MIRA_MCP_TOKEN
```

Confira com `codex mcp list`.

</Tab>
</Tabs>

## Permissões [#permissões]

O agente age com as permissões do dono do token: vê só os projetos de que a pessoa é membro, ou todos quando ela é admin. Em cada projeto, a permissão efetiva é a interseção do token com o **teto do projeto**. Um eixo desativado em qualquer um dos dois fica desativado.

| Eixo | O que libera |
| --- | --- |
| Screenshot, console, rede, erros | Ler o anexo desse tipo com `get_attachment` |
| Comentar | `add_comment` |
| Alterar reports | `update_report` |
| Selo "via agente" | Comentários do agente aparecem com o selo |

Replay e gravação de tela nunca chegam ao agente.

### Teto do projeto [#teto-do-projeto]

Um admin ou Mantenedor ajusta o teto em **Configurações do projeto → Agentes de IA**. Ele usa os mesmos eixos do token, sem o selo. Sem teto salvo, tudo fica liberado. Um projeto que testa com dados reais pode desmarcar console e rede, e nenhum agente lê essas evidências ali, qualquer que seja o token.

Na mesma seção ficam os **repositórios de código** do projeto, um por linha, como `owner/name` ou URL. O agente usa a lista para conferir se o diretório onde trabalha é o código da app.

## Tools [#tools]

| Tool | Uso |
| --- | --- |
| `list_projects` | Projetos que o dono do token acessa |
| `list_reports` | Reports com os filtros da listagem. Sem filtro de status, só `triaged` (**A fazer**) |
| `get_report` | Descrição, contexto, anexos, comentários, vínculos com Jira e GitHub e repositórios de código do projeto |
| `get_attachment` | Screenshot como imagem. Console, rede e erros como texto truncado |
| `add_comment` | Comenta no report |
| `update_report` | Status, prioridade, tags, responsável, título e descrição. Para `duplicate`, informe também `duplicateOfId`, o id do original |

`update_report` é marcada como escrita, então o cliente pede confirmação a cada chamada. Marcar `in_progress` atribui o report ao dono do token quando não há responsável, e é recusado quando o responsável é outra pessoa.

## Prompt `implement_report` [#prompt-implement_report]

O prompt recebe o id do report (`reportId`, opcional). Sem id, o agente lista os reports **A fazer** e a pessoa escolhe um. Depois, o agente:

1. Lê o report e a evidência permitida.
2. Confere se o diretório atual é um dos repositórios de código do projeto e avisa se não for.
3. Marca o report como `in_progress`.
4. Implementa seguindo as regras do repositório e roda os testes.
5. Cita a issue vinculada no commit e no PR, como `Fixes owner/repo#123`.
6. Comenta no report o que mudou, com o link do PR.

O agente nunca marca `resolved` por conta própria. Qualquer outra alteração depende de pedido ou aprovação da pessoa. É um report por vez.

No Claude Code, o prompt aparece como `/mcp__mira__implement_report`. O Codex ainda não usa prompts MCP, só as tools. Nele, peça o fluxo em texto:

```text
Pelo MCP mira, implemente o report <id>: leia o report e a evidência, confira se este diretório é um dos repositórios de código do projeto, marque o report como in_progress, implemente seguindo as regras do repositório, rode os testes, cite a issue vinculada no commit e no PR e comente no report o que mudou com o link do PR. Não marque resolved e não faça outra alteração no report sem me perguntar.
```

## Auditoria e privacidade [#auditoria-e-privacidade]

Toda escrita pelo MCP grava a origem `mcp` na atividade do report, e o dashboard mostra o rótulo **agente** ao lado dela. O selo **via agente** no comentário segue a opção do token. Sem o selo, o comentário aparece como da pessoa, e a origem continua registrada.

<Callout type="warning" title="A evidência vai para o provedor do modelo">
O que o agente lê vai para o provedor do modelo, como a Anthropic ou a OpenAI. A redação da captura continua valendo, mas não remove tudo. Antes de liberar console e rede, confira se o projeto testa com dados reais. O teto do projeto corta esses tipos para todos os agentes.
</Callout>

## Revogar [#revogar]

Em **Tokens de agente**, abra o menu **…** do token e escolha **Revogar**. O agente recebe 401 na chamada seguinte. Remova também a configuração local:

```bash
claude mcp remove mira --scope user
codex mcp remove mira
```

Desativar o usuário ou trocar a senha dele também revoga os tokens de agente.

## Próximos passos [#próximos-passos]

<Cards>
<Card href="/desenvolvedores/cli" title="CLI" description="Diferenças entre a CLI e o MCP." />
<Card href="/desenvolvedores/tokens" title="Tokens" description="Os tipos de credencial do Mira e quando usar cada um." />
</Cards>