---
title: MCP e traces
description: Observabilidade read-only, eventos append-only e recursos expostos.
context: Como consultar artefatos e traces sem substituir a fonte canônica local.
---

# MCP e traces

O MCP do SDD é read-only. Ele expõe artefatos, contexto, handoff, readiness, traces, clients doctor, capabilities, manifesto de agents e adapters runtime para consulta. Ele não aprova checkpoints, não grava artefatos e não substitui `traceability-map.yaml`.

## Servidor MCP

```bash
sdd mcp serve --root .
sdd mcp config --targets all --root .
sdd mcp doctor --root . --json
```

Use `.mcp.json` e `.cursor/mcp.json` em projetos consumidores quando precisar conectar clients MCP. Esses arquivos podem carregar paths absolutos e não devem ser versionados no repositório da camada.

## Leituras principais

| Superfície | Uso |
|---|---|
| `sdd_context_bundle` | Primeira leitura antes de gerar ou executar; agrega Context Pack, artifact status, busca local, traces, capabilities, runtime adapters e chamadas CodeGraph recomendadas |
| `sdd_readiness_summary` | Cockpit `ready | warn | blocked` com MCP doctor, `sdd health`, auto/workflow status, freshness de cache, capabilities, quality report e próximos comandos |
| `sdd_context_handoff` | Handoff curto para stage atual, útil quando o agent precisa economizar contexto |
| `sdd_agents_manifest` | Manifesto do agente `sdd-orchestrator` e papéis SDD disponíveis |

Resources derivados expostos pelo MCP incluem `sdd://auto/status`, `sdd://workflow/{id}/status`, `sdd://quality/{slug}`, `sdd://context-bundle/{orchestration}/{stage}`, `sdd://handoff/{orchestration}/{stage}`, `sdd://agents/{agent_id}` e `sdd://runtime/adapters`.

## Traces

```bash
sdd trace list
sdd trace show <id>
sdd trace summary --orchestration "minha feature" --json
sdd trace doctor
```

## Eventos

| Campo | Regra |
|---|---|
| `agent` | Client/adapter efetivamente invocado |
| `selected_model` | Modelo resolvido pelo SDD |
| `observed_model` | Modelo reportado pelo provider quando houver metadata confiável |
| `confidence` | `observed`, `estimated` ou `unreported` |
| `usage` | Tokens/custo real ou estimado quando possível |

Não inferir `observed_model` a partir de config. Quando o provider não reporta metadata, preserve `selected_model` e marque confiança como não reportada.

## ACP

```bash
sdd acp serve --root .
sdd acp doctor --root . --json
sdd acp config --targets zed --dry-run
```

ACP expõe uma sessão para o agente `sdd-orchestrator`. Sessões ficam em `.sdd/acp/sessions/<session_id>.json` como cache redigido; artefatos, checkpoints e rastreabilidade continuam canônicos no CLI e em `docs/<slug>/`.
