@polymorphism-tech/morph-spec 8.34.2 → 8.35.1

package/framework/standards/ai-agents/llm-runtime-defaults.md

@@ -0,0 +1,226 @@
+# LLM Runtime Defaults — timeout, retry, strict, amostragem e o pin do SDK
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 1 (on-keyword)
+> **Keywords:** llm defaults, runtime defaults, timeout llm, retry llm, strict json schema, temperature reasoning, capability por alias, network timeout, pin de sdk
+> **Read by Claude in:** implement (ao configurar cliente, alias ou opções de chamada) e troubleshoot (chamada pendurada, 400 recorrente, quebra binária)
+
+**Verified against:** Microsoft.Extensions.AI 10.9.0 + Microsoft.Agents.AI 1.20.0 + OpenAI 2.13.0 (ai-pin 2026-09-08); provado por `templates/dotnet/ai-kit/src/Morph.AiKit/Providers/ModelAlias.cs` e `.../Providers/ModelRegistry.cs` (alias, `api:`, e limite por alias com procedência obrigatória). A superfície do SDK citada aqui — `ChatOptions`, `ChatResponseFormatJson`, `ReasoningEffort`, `OpenAIClientOptions` — foi **medida por reflexão sobre as assemblies do pin** em 2026-09-08. O timeout é **provado por** `.../Agents/AgentSpecOptions.cs` e `.../Agents/AgentFactory.cs`, que o kit compila **por spec** (`TimeoutSeconds` vira um cliente de timeout no pipeline) — e **não** por alias: a allowlist de alias do registry não tem chave de timeout (medido). Os valores default do retry do `System.ClientModel` 1.15.0 são **verificação documental** — essa assembly está fora do conjunto que o probe carrega. Last-verified: 2026-09-08.
+
+---
+
+## Fronteira com o Model Registry
+
+`ai-agents-providers-model-registry` é **Layer 0** (sempre carregado) e continua dono do **schema**:
+o formato do documento, `defaultAlias`, o fallback e a tabela de providers. **Este** standard é dono
+dos **valores e dos botões de runtime**: timeout, retry, strict, amostragem, esforço de raciocínio e
+o pin de versão do SDK.
+
+Sem esta fronteira escrita, o par vira **duas verdades sobre o mesmo JSON** — e a segunda verdade é
+sempre a que alguém encontra primeiro.
+
+Complemento: `ai-agents-agent-spec` é dono da **forma** do agente e da regra "nulo = não envia";
+`ai-agents-cost-and-budget` é dono de `pricing`. Aqui não se repete nenhum dos três.
+
+---
+
+## Retry herdado
+
+**Não escreva um loop de retry sobre chamada de LLM.** A pilha do `System.ClientModel` — a base dos
+clientes gerados da OpenAI — já traz uma política de retry, e ela é aplicada por padrão.
+
+O que a assembly `System.ClientModel` 1.15.0 (a restaurada junto com o pin) carrega nos metadados,
+**medido por leitura de literal em 2026-09-08**: `ClientRetryPolicy`, `ClientPipelineOptions`,
+`RetryPolicy`, `MaxRetries`, `DefaultMaxRetries`, `DefaultInitialDelay`, `ShouldRetry`,
+`GetNextDelay`. Isto prova que os pontos de extensão existem e como se chamam.
+
+**Verificação documental** (fonte primária: o fonte de `ClientRetryPolicy` em
+`Azure/azure-sdk-for-net`, lido em 2026-09-08), e por isso escrita como valor a **conferir** antes de
+depender dela: 3 tentativas de retry, atraso inicial de 0,8 s, backoff exponencial na forma
+`(1 << (tryCount - 1)) * initialDelay`, e o cabeçalho de espera do servidor respeitado quando ele
+pede mais tempo do que o backoff calculado.
+
+**A regra:** herde. Se precisar de outro número, **substitua a política** (`RetryPolicy` nas opções
+do cliente), não empilhe um `for` por cima. Duas camadas de retry multiplicam: 3 × 3 = 9 chamadas
+pagas para um incidente que o operador vê como "uma".
+
+Prática de campo alinhada, com a razão escrita no próprio código: *"não adicionamos loop próprio"*.
+
+---
+
+## Timeout explícito
+
+**Retry sobre uma chamada que nunca expira é o pior dos dois mundos.** A política tenta de novo o
+que ainda não desistiu, e o incidente aparece como latência infinita em vez de erro.
+
+Dois fatos medidos por reflexão sobre as assemblies do pin, em 2026-09-08:
+
+1. **`Microsoft.Extensions.AI.ChatOptions` não tem propriedade de timeout.** As 20 propriedades
+   declaradas são de conteúdo da chamada (`Temperature`, `TopP`, `TopK`, `MaxOutputTokens`,
+   `ResponseFormat`, `Tools`, `ToolMode`, `Reasoning`, `Seed`, `StopSequences`, `Instructions`,
+   `ModelId`, `ConversationId`, `AdditionalProperties`, …). A abstração **não sabe expressar**
+   timeout — logo, ele não é um botão por chamada nesse nível.
+2. **`OpenAI.OpenAIClientOptions` (OpenAI 2.13.0) declara apenas** `Endpoint`, `OrganizationId`,
+   `ProjectId` e `UserAgentApplicationId`. O botão de timeout **não é dele**: ele vem da base,
+   `System.ClientModel.Primitives.ClientPipelineOptions`, cuja assembly carrega os nomes
+   `NetworkTimeout` e `get_NetworkTimeout` (medido por literal na mesma data). A declaração está
+   fora do conjunto de assemblies que o probe carrega, então este ponto é **documental**.
+
+**A regra, em três partes:**
+
+- **Configure o timeout explicitamente**, e escolha conscientemente a camada. O exemplar do kit o faz **por spec de agente** (`AgentSpecOptions.TimeoutSeconds` → um cliente de timeout no pipeline), porque a allowlist de alias do registry **não tem** chave de timeout — medido. Por alias exige abrir essa allowlist, o que é mudança de `.cs`. Alias
+  de raciocínio pesado e alias de resposta curta não têm o mesmo tempo aceitável.
+- **`CancellationToken` de turno não é timeout de chamada.** Ele cancela quando *alguém* desiste
+  (o usuário fechou a aba, o job foi abortado). Uma chamada pendurada sem ninguém para desistir
+  fica pendurada.
+- **Timeout curto sem retry é fragilidade; retry sem timeout é vazamento.** Os dois andam juntos.
+
+Medições que motivam a regra: um projeto do acervo tem **apenas** o `CancellationToken` do turno,
+sem nenhum timeout de chamada. Outro tem uma biblioteca de resiliência declarada no `.csproj`
+**sem aplicá-la à camada de IA**, e nenhum timeout de `HttpClient` nem handler de resiliência
+padrão registrado.
+
+> **Correção explícita de premissa.** A formulação "timeout é herdado do SDK, como o retry" é
+> **falsa** nas duas pontas medidas: o retry é herdado, o timeout precisa ser **decidido**. Herdar
+> o que não existe é como se descobre que uma chamada roda até o processo morrer.
+
+---
+
+## Strict JSON schema por alias
+
+O identificador **`StrictJsonSchema` não existe**. Medição, 2026-09-08: uma varredura por reflexão
+sobre as **14 assemblies** dos pacotes do pin e das pontes (`Microsoft.Agents.AI` e derivados,
+`Microsoft.Extensions.AI` e derivados, `OpenAI`, `Google.GenAI`, `ModelContextProtocol` e derivados,
+`Microsoft.Extensions.VectorData.Abstractions`) devolve **zero** tipos exportados cujo nome contenha
+`Strict`.
+
+E `Microsoft.Extensions.AI.ChatResponseFormatJson` declara exatamente três propriedades — `Schema`,
+`SchemaDescription`, `SchemaName` — e **nenhum campo `strict`**, também medido por reflexão. A
+abstração não sabe expressar strict.
+
+O mecanismo real é **uma chave em `ChatOptions.AdditionalProperties`**, lida pela ponte do provider,
+que transforma o schema antes de enviá-lo (proibir propriedades adicionais, converter schemas
+booleanos). Isso significa três coisas para o desenho:
+
+- **Strict é decisão por chamada / por alias**, porque é onde `ChatOptions` vive.
+- **Suporte a strict é capacidade do modelo**, e o registry já sabe o provider e o modelo de cada
+  alias. Logo o lugar do "este alias suporta strict" é o **alias**.
+- **Nunca uma flag global de processo.**
+
+### O anti-padrão, com o nome real do campo
+
+Medido em produção no acervo: um par `StrictJsonSchemaSupported` (propriedade de configuração) +
+`volatile bool _strictUnsupported` (campo estático de processo). Ao receber um `400` de qualquer
+chamada, o campo é ligado e **todas as chamadas seguintes do processo** passam a ser enviadas sem
+strict. A frase do próprio diagnóstico do projeto: *"um 400 em qualquer ponto degrada todas as
+chamadas seguintes"*.
+
+O efeito prático: um modelo local em desenvolvimento, que legitimamente não suporta strict, rebaixa
+as chamadas de **produção** do mesmo processo. Capacidade é do alias; degradação global é um bug
+disfarçado de resiliência.
+
+O kit compila a forma correta dessa ideia: limites conhecidos de um alias vivem num record de
+`Constraints` **por alias**, e um limite **sem procedência escrita é recusado na carga do
+registry** — para que ninguém consiga gravar um "todo mundo sabe que" sem dizer de onde tirou.
+
+---
+
+## Temperature e reasoning
+
+**Modelo de raciocínio e amostragem não se misturam.** A regra prática: `Temperature` só faz sentido
+em modelo sem raciocínio; em modelo de raciocínio o botão é o **esforço**.
+
+O que está **medido por reflexão** sobre `Microsoft.Extensions.AI.Abstractions` 10.9.0, em
+2026-09-08:
+
+- `ChatOptions.Temperature` (`float?`) e `ChatOptions.Reasoning` (`ReasoningOptions`) são
+  propriedades **distintas** e independentes.
+- `ReasoningOptions` declara `Effort` e `Output`.
+- `ReasoningEffort` é um **enum de primeira classe** com exatamente cinco valores:
+  `None = 0`, `Low = 1`, `Medium = 2`, `High = 3`, `ExtraHigh = 4`.
+
+Esforço de raciocínio, portanto, é **tipado** — não é string, e não precisa de convenção de projeto.
+
+A **medição de campo** que sustenta o limite prático (dois modelos de raciocínio que rejeitam
+`Temperature != 1` quando há tools na chamada) é de `ai-agents-providers-model-registry` — Layer 0,
+sempre carregado, e dono dela desde a re-verificação anterior. **Não é repetida aqui**: uma segunda
+cópia da mesma medição é a segunda verdade que a seção de fronteira acima existe para evitar. O que
+este standard acrescenta é onde o limite mora e o que ele governa.
+
+**Contra-evidência, e ela é instrutiva:** outro projeto do acervo **não configura parâmetro de
+amostragem nenhum** e roda no default do SDK. Não configurar é uma escolha válida, e mais honesta
+que configurar errado. A regra final é: **configure quando você mediu que precisa; caso contrário,
+não envie** (`ai-agents-agent-spec`, "nulo = não envia").
+
+Onde o limite mora: no **alias**, como `Constraints` com procedência — a mesma forma que o kit
+compila para `ToolCallingRequiresReasoningEffortNone` e `TemperatureUnsupported`. Um limite por
+alias é verificável antes da chamada; um limite espalhado em `if`s só é verificável depois do 400.
+
+---
+
+## Pin de SDK e compatibilidade binária
+
+**Faixa flutuante em SDK de IA custa dinheiro.** Não é uma preferência de estilo: é um incidente
+medido.
+
+O caso, do acervo: um projeto referenciava o SDK da OpenAI numa faixa `2.*`. O NuGet resolveu para
+uma versão menor mais nova, um membro de conteúdo de resposta **mudou de assinatura**, e a chamada
+estourou `MissingMethodException` **depois de a requisição já ter sido paga** — o dinheiro saiu, a
+resposta não chegou ao domínio. A correção foi pinar a versão exata, com oito linhas de comentário
+explicando por quê.
+
+**As três regras:**
+
+1. **Pin exato** (`[2.13.0]`, não `2.*`) para todo pacote de IA. Neste framework a fonte única é
+   `framework/ai-pin.json`, e nenhum standard escreve versão à mão.
+2. **A faixa e o pacote de ponte andam juntos.** `Microsoft.Extensions.AI.OpenAI` referencia uma
+   versão do `OpenAI`; carregar outra em runtime é uma quebra binária esperando um caminho de código
+   pouco exercitado.
+3. **Teste de compatibilidade binária como rede de segurança** — comparar a versão do assembly
+   carregado com a que a ponte referencia, e conferir a **assinatura** do membro que já quebrou uma
+   vez. A técnica está em `ai-agents-testing-ai`.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Por quê é problema | Solução |
+|---|---|---|
+| Loop de retry próprio sobre a chamada de LLM | Multiplica com o retry do SDK: 3 × 3 = 9 chamadas pagas por incidente | Herde; para outro número, substitua a política |
+| Chamada de LLM sem timeout | Retry sobre o que nunca expira; o incidente vira latência infinita | Timeout explícito — por spec de agente (o exemplar do kit) ou por alias, se a allowlist foi aberta |
+| `CancellationToken` de turno usado como timeout | Só cancela quando alguém desiste; ninguém desiste de um job noturno | Timeout explícito, além do token |
+| Flag global de processo para strict | Um 400 em dev rebaixa produção no mesmo processo | Capacidade por alias, em `Constraints` com procedência |
+| `Temperature` em modelo de raciocínio | Erro do provider, ou pior: silenciosamente ignorado | Esforço tipado (`ReasoningEffort`) para raciocínio; amostragem só sem raciocínio |
+| Parâmetro de amostragem configurado "por garantia" | Envia valor que ninguém mediu, e some no default do provider | Nulo = não envia |
+| Faixa flutuante (`2.*`) em pacote de IA | Quebra binária depois da chamada paga | Pin exato, a partir de `framework/ai-pin.json` |
+| Limite de alias escrito como regra universal em C# | Vira folclore sem procedência, e ninguém sabe revogá-lo | Campo do alias, com procedência obrigatória |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] Nenhum loop de retry escrito à mão em volta de uma chamada de LLM
+- [ ] Há timeout explícito (por spec de agente, como o exemplar do kit, ou por alias se a allowlist foi aberta), e ele **não** é o `CancellationToken` do turno
+- [ ] Nenhuma flag estática de processo governa strict ou qualquer outra capacidade
+- [ ] Capacidade e limite são campos do **alias**, com procedência escrita
+- [ ] Nenhuma ocorrência de um tipo chamado `StrictJsonSchema` (ele não existe em nenhum pacote do pin)
+- [ ] Esforço de raciocínio usa o enum `ReasoningEffort`, não string
+- [ ] `Temperature` não é enviada junto com esforço de raciocínio
+- [ ] Todo pacote de IA está pinado em versão exata, derivada de `framework/ai-pin.json`
+- [ ] Existe um teste de compatibilidade binária cobrindo o par SDK × ponte
+
+---
+
+## References
+
+- `ai-agents-providers-model-registry` — Layer 0: o **schema** do documento, `defaultAlias`, fallback
+  e a tabela de providers. Este standard não repete nada disso
+- `ai-agents-agent-spec` — a forma do agente e a regra "nulo = não envia"
+- `ai-agents-cost-and-budget` — `pricing` por alias, cálculo e teto de gasto
+- `ai-agents-testing-ai` — o teste de compatibilidade binária, e como exercitar opções sem rede
+- `ai-agents-structured-output` — o schema da saída, cujo strict este standard governa
+- `framework/ai-pin.json` — a fonte única das versões; nenhuma versão é digitada num standard
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/llm-runtime-defaults.md v1.0 (2026-09-08)*

package/framework/standards/ai-agents/mcp-server.md

@@ -2,10 +2,10 @@
 
 > **Scope:** stacks=["dotnet"]
 > **Layer:** 2 (on-keyword)
-> **Keywords:** mcp server, expose mcp, build mcp server, mcp host, publish tools, McpServerTool, AddMcpServer
+> **Keywords:** mcp server, expose mcp, build mcp server, mcp host, publish tools, McpServerTool, AddMcpServer, request filters, stateless, spec 2026-07-28
 > **Read by Claude in:** implement (quando um projeto expõe capacidades como MCP server para consumo externo)
 
-**Verified against:** MAF 1.0 GA + ModelContextProtocol C# SDK server-side (`[McpServerToolType]`/`[McpServerTool]`, `WithStdioServerTransport`/`WithHttpTransport`, `ModelContextProtocol.AspNetCore`). Last-verified: 2026-05-19.
+**Verified against:** ModelContextProtocol 2.2.0 + ModelContextProtocol.AspNetCore 2.2.0 (ai-pin 2026-09-08; o `.AspNetCore` não está no pin — versão apurada no nuget.org em 2026-09-08) + revisão de spec MCP **2026-07-28** (modelcontextprotocol.io/specification/versioning, lido 2026-09-08). **Verificação documental — o ai-kit não exercita MCP**, e por isso este standard NÃO carimba `provado por`. Os nomes de tipo, os defaults e os avisos de obsolescência abaixo foram **medidos por reflexão sobre as assemblies 2.2.0** em 2026-09-08. Last-verified: 2026-09-08.
 
 ---
 
@@ -30,26 +30,63 @@ Crie um MCP server quando você quer **expor capacidades do projeto** de forma p
 
 ## A API
 
+### Não existe "MCP 2.0" como revisão de especificação
+
+A confusão vale ser desfeita antes de qualquer código, porque ela muda o que se procura na documentação:
+
+| Coisa | Como é versionada | Valor corrente (2026-09-08) |
+|---|---|---|
+| **A especificação MCP** | por **data** | revisão **`2026-07-28`** (sucede `2025-11-25`) |
+| **O SDK C# `ModelContextProtocol`** | SemVer | **2.2.0**, publicado 2026-08-13 |
+
+"MCP 2.0" é a **major do SDK**, nunca uma revisão de spec. Fonte: modelcontextprotocol.io/specification/versioning e o changelog da revisão `2026-07-28`, lidos em 2026-09-08.
+
+### O que a revisão `2026-07-28` mudou para quem escreve servidor
+
+- **Sessões removidas** — o cabeçalho `Mcp-Session-Id` deixou de existir (**SEP-2567**).
+- **`initialize` / `notifications/initialized` removidos** — versão e capacidades viajam em `_meta` **por request** (**SEP-2575**).
+- Novo RPC **`server/discover`**.
+- **`ping`, `logging/setLevel` e `notifications/roots/list_changed` removidos.**
+- **Roots, Sampling e Logging deprecados** (**SEP-2577**).
+- **Tasks** (long-running) saíram do core para a extensão `io.modelcontextprotocol/tasks`.
+- **Elicitation/sampling substituídos por MRTR** — `InputRequiredResult` + `InputRequest.ForElicitation(...)` (**SEP-2322**).
+- **Resultado cacheável** — `ICacheableResult` com `TimeToLive` e `CacheScope` (**SEP-2549**).
+- **HTTP+SSE formalmente Deprecated** (Streamable HTTP é o transporte).
+
+> **Duas dessas afirmações não dependem do changelog: elas estão gravadas na assembly.** Medido em `ModelContextProtocol.AspNetCore` 2.2.0 e `ModelContextProtocol.Core` 2.2.0, no texto do `[Obsolete]` de cada membro:
+> - `HttpServerTransportOptions.EventStreamStore`/`IdleTimeout`/`MaxIdleSessionCount`/`PerSessionExecutionContext`/`SessionMigrationHandler` — *"Stateful Streamable HTTP mode is a back-compat-only escape hatch for 2025-11-25 protocol revision clients and earlier. Set `HttpServerTransportOptions.SessionMode = HttpServerSessionMode.Stateless` (**the default as of the 2026-07-28 protocol revision**) for new code. See SEP-2567."*
+> - `McpServerOptions.MaxSamplingOutputTokens` — *"The Sampling feature is deprecated as of specification version 2026-07-28 … See SEP-2577."*
+> - `HttpServerTransportOptions.EnableLegacySse` — obsoleto: *"…Use Streamable HTTP instead."*
+
+### A API C# de servidor NÃO mudou de nome
+
+`AddMcpServer()`, `WithStdioServerTransport()`, `WithHttpTransport(...)`, `WithToolsFromAssembly()`, `WithTools([...])`, `[McpServerToolType]`, `[McpServerTool]`, `McpServerTool.Create(...)` e `app.MapMcp()` continuam iguais. **O que mudou é o default**, não a grafia.
+
 **Packages:**
 
 ```xml
-<!-- SDK cliente+servidor do protocolo MCP -->
-<PackageReference Include="ModelContextProtocol" Version="0.1.*" />
+<!-- SDK cliente+servidor do protocolo MCP — no ai-pin.json -->
+<PackageReference Include="ModelContextProtocol" Version="2.2.0" />
 
-<!-- Pacote base MAF (para AsAIAgent, AsAIFunction) -->
-<PackageReference Include="Microsoft.Agents.AI" Version="1.0.*" />
+<!-- Pacote base MAF (para AsAIAgent, AsAIFunction) — no ai-pin.json -->
+<PackageReference Include="Microsoft.Agents.AI" Version="1.20.0" />
 
-<!-- Apenas se o transporte for HTTP (server-side) -->
-<PackageReference Include="ModelContextProtocol.AspNetCore" Version="0.1.*" />
+<!-- Apenas se o transporte for HTTP (server-side).
+     NÃO está no ai-pin.json; versão apurada no nuget.org em 2026-09-08. -->
+<PackageReference Include="ModelContextProtocol.AspNetCore" Version="2.2.0" />
 ```
 
-> `ModelContextProtocol` versão 0.1.* (preview) — GA previsto. Verifique versão corrente no NuGet antes de travar.
+### Stateless é o DEFAULT, não uma escolha
+
+Medido em `ModelContextProtocol.AspNetCore` 2.2.0, instanciando `HttpServerTransportOptions` e lendo os valores iniciais: **`SessionMode == HttpServerSessionMode.Stateless`** e `Stateless == true`. Os valores de `HttpServerSessionMode` são `Stateless` (0), `Stateful` (1) e `StatefulForInitializeClients` (2).
+
+Escrever `o.Stateless = true` hoje é redundante; escrever `o.SessionMode = HttpServerSessionMode.Stateful` é **optar por um escape hatch de compatibilidade** com clientes da revisão `2025-11-25` e anteriores — e é isso que a mensagem de obsolescência diz. A versão anterior deste standard apresentava stateless como uma decisão de escala do autor; o protocolo já a tomou.
 
 **Dois jeitos de declarar tools:**
 
 | Padrão | Quando usar |
 |--------|-------------|
-| Atributos `[McpServerToolType]` + `[McpServerTool]` | Tools são métodos estáticos do projeto — padrão canônico do SDK. Descoberta automática via `WithToolsFromAssembly()`. |
+| Atributos `[McpServerToolType]` + `[McpServerTool]` | Tools são métodos do projeto — padrão canônico do SDK. Descoberta automática via `WithToolsFromAssembly()`. |
 | `McpServerTool.Create(...)` | Embrulhar um agente MAF (`agent.AsAIFunction()`) ou um `AIFunction` construído em runtime como tool. |
 
 **Padrão de servidor (stdio):**
@@ -63,7 +100,7 @@ Tools ([McpServerTool] ou McpServerTool.Create)
     → Host.Build().RunAsync()            // sobe o servidor
 ```
 
-**Transport stdio** é o padrão para servidores locais (subprocessos, Claude Code tools). **HTTP server-side** usa o pacote `ModelContextProtocol.AspNetCore`: troque `WithStdioServerTransport()` por `WithHttpTransport(o => o.Stateless = true)` e exponha o endpoint com `app.MapMcp()` num `WebApplication`.
+**Transport stdio** é o padrão para servidores locais (subprocessos, Claude Code tools). **HTTP server-side** usa o pacote `ModelContextProtocol.AspNetCore`: troque `WithStdioServerTransport()` por `WithHttpTransport()` e exponha o endpoint com `app.MapMcp()` num `WebApplication`.
 
 ---
 
@@ -148,7 +185,7 @@ var builder = WebApplication.CreateBuilder(args);
 
 builder.Services
     .AddMcpServer()
-    .WithHttpTransport(options => options.Stateless = true)  // stateless: escalável
+    .WithHttpTransport()          // SessionMode = Stateless já é o default (medido em 2.2.0)
     .WithToolsFromAssembly();
 
 var app = builder.Build();
@@ -157,9 +194,64 @@ app.MapMcp();   // expõe o endpoint MCP (Streamable HTTP)
 app.Run();
 ```
 
-> `Stateless = true` é recomendado para servidores que não precisam de requests server-to-client
-> (sampling/elicitation) — escala melhor e dispensa gestão de sessão. Para HTTP em produção,
-> proteja `MapMcp()` com autenticação — ver seção Segurança.
+> Não escreva `options.Stateless = true`: é redundante desde a revisão `2026-07-28`. Se você
+> precisar de `SessionMode = HttpServerSessionMode.Stateful`, saiba que está optando por um
+> **escape hatch de compatibilidade** com clientes antigos — o próprio SDK diz isso no
+> `[Obsolete]`. Para HTTP em produção, proteja `MapMcp()` com autenticação — ver seção Segurança.
+
+---
+
+## Filtros de request — listar não é poder chamar
+
+Este é o mecanismo que permite **um servidor MCP servir vários tenants** sem um processo por tenant. A API foi medida em `ModelContextProtocol` 2.2.0 (`McpRequestFilterBuilderExtensions`) e `ModelContextProtocol.AspNetCore` 2.2.0 (`HttpMcpServerBuilderExtensions`).
+
+```csharp
+services.AddMcpServer()
+    .WithListToolsHandler(async (context, ct) => new ListToolsResult { Tools = GetTools() })
+    .WithRequestFilters(f =>
+    {
+        // (1) Poda a LISTAGEM — o cliente não vê a tool.
+        f.AddListToolsFilter(next => async (context, ct) =>
+        {
+            var result = await next(context, ct);
+            result.Tools = [.. result.Tools.Where(t => AllowedFor(context.User, t))];
+            return result;
+        });
+
+        // (2) Bloqueia a CHAMADA — sem isto, quem souber o nome chama assim mesmo.
+        f.AddCallToolFilter(next => async (context, ct) =>
+        {
+            if (!AllowedFor(context.User, context.Params!.Name))   // ClaimsPrincipal por request
+                throw new McpException("tool not available for this principal");
+            return await next(context, ct);
+        });
+    })
+    .AddAuthorizationFilters();   // a ORDEM importa — ver abaixo
+```
+
+**Duas regras que este standard existe para gravar:**
+
+1. **São DOIS filtros, não um.** `AddListToolsFilter` **esconde** a tool; só `AddCallToolFilter` **impede chamá-la**. Um cliente que já conhece o nome — porque leu a lista antes, porque outro tenant tem a mesma tool, ou porque adivinhou — chama direto. Poda de listagem é ergonomia, não autorização.
+2. **Cliente já conectado não relê a lista até reconectar.** Revogar acesso podando a listagem não revoga nada para quem já está dentro. A revogação real é o filtro de `CallTool`.
+
+**A ordem do encadeamento é semântica:** um filtro registrado **antes** de `AddAuthorizationFilters()` roda com a lista **completa** — vê todas as tools, inclusive as que a autorização removeria. Se a intenção é filtrar o que já passou pela autorização, registre depois.
+
+Filtros disponíveis (medidos): `AddListToolsFilter`, `AddCallToolFilter`, `AddListPromptsFilter`, `AddGetPromptFilter`, `AddListResourcesFilter`, `AddReadResourceFilter`, `AddListResourceTemplatesFilter`, `AddCompleteFilter`, `AddSubscribeToResourcesFilter`, `AddUnsubscribeFromResourcesFilter`, `AddSetLoggingLevelFilter`.
+
+### Identidade por request
+
+- **`context.User`** é o `ClaimsPrincipal` do request, disponível dentro do filtro.
+- Uma tool pode receber por **injeção de parâmetro**: `ClaimsPrincipal`, `RequestContext<T>`, `McpServer` e `IProgress<T>`. O escopo de DI é **por request** — `McpServerOptions.ScopeRequests` tem default **`true`** (medido). `[FromKeyedServices]` funciona.
+- **`HttpServerTransportOptions.ConfigureSessionOptions`** permite montar o `ToolCollection` a partir do `HttpContext.User` — poda no nascimento da sessão, complementar (não substituta) ao filtro de `CallTool`.
+
+### Argumento de tool é input NÃO confiável
+
+O que chega nos argumentos foi escrito por um modelo, a partir de texto que um humano digitou. Trate como entrada hostil:
+
+- **Allow-list** de valores onde houver conjunto finito; nunca `switch` com `default:` permissivo.
+- **Limite de tamanho** em toda string antes de tocar I/O.
+- **Query parametrizada**, sempre — nunca concatenação com o argumento.
+- **Id de tenant vem da closure ou da credencial, NUNCA do modelo.** Uma tool que aceita `tenantId` como parâmetro é uma tool que qualquer prompt injection reaponta para outro cliente.
 
 **Registrar no Claude Code (`settings.json` do projeto consumidor):**
 
@@ -218,6 +310,10 @@ prefira o tipo de instância resolvido por DI a métodos estáticos com estado g
 | Expor tools sem validação de input | Agentes externos (ou alucinações de LLM) podem enviar dados malformados | Validar todos os parâmetros antes de qualquer I/O |
 | Tools sem escopo definido — expor tudo "por conveniência" | Superfície de ataque ampla; dificulta manutenção | Expor apenas o necessário; revisar a lista a cada release |
 | HTTP transport sem autenticação | Qualquer processo na rede pode invocar as tools | Bearer token / API key obrigatório em HTTP; stdio é suficiente para uso local |
+| **Podar só a listagem e chamar isso de autorização** | `ListTools` filtrado esconde a tool; quem sabe o nome chama assim mesmo, e cliente conectado não relê a lista | `AddListToolsFilter` **e** `AddCallToolFilter` |
+| **`tenantId` como parâmetro de tool** | O argumento é escrito pelo modelo: prompt injection reaponta para outro cliente | Tenant vem da closure ou de `context.User` |
+| Escrever `options.Stateless = true` "para escalar" | Redundante desde a revisão `2026-07-28`; sugere que há uma decisão a tomar onde não há | `WithHttpTransport()` sem argumento |
+| Contar com `initialize`, `Mcp-Session-Id`, `ping` ou `logging/setLevel` | Removidos na revisão `2026-07-28` | Versão/capacidades em `_meta` por request; `server/discover` |
 | Subir o MCP server no mesmo processo da aplicação principal | Acoplamento; falha no servidor MCP afeta a app | Projeto separado (`MyProject.McpServer`) com entrypoint próprio |
 
 ---
@@ -226,13 +322,16 @@ prefira o tipo de instância resolvido por DI a métodos estáticos com estado g
 
 - [ ] `ModelContextProtocol` e `Microsoft.Agents.AI` no `.csproj`; `ModelContextProtocol.AspNetCore` apenas se HTTP
 - [ ] Tools declaradas via `[McpServerToolType]` + `[McpServerTool]` (estáticas) ou `McpServerTool.Create(...)` (agente MAF / runtime)
-- [ ] `AddMcpServer()` com `WithStdioServerTransport()` (stdio) ou `WithHttpTransport(o => o.Stateless = true)` (HTTP)
+- [ ] `AddMcpServer()` com `WithStdioServerTransport()` (stdio) ou `WithHttpTransport()` (HTTP) — sem reafirmar o default `Stateless`
 - [ ] `WithToolsFromAssembly()` para tools por atributo, ou `WithTools([...])` para tools de runtime
 - [ ] Entrypoint: `await builder.Build().RunAsync()` (stdio) ou `app.MapMcp(); app.Run()` (HTTP)
 - [ ] Agente criado via `_modelRegistry.GetChatClient("alias").AsAIAgent(...)` — provider-agnostic
 - [ ] Validação de input em todas as tools antes de executar lógica de negócio
 - [ ] Escopo mínimo: apenas tools necessárias para o consumidor externo
 - [ ] HTTP transport (se usado) protegido por autenticação
+- [ ] Multi-tenant: existe `AddCallToolFilter`, e não apenas `AddListToolsFilter`
+- [ ] Nenhuma tool recebe id de tenant como parâmetro
+- [ ] Nenhum `PackageReference` com faixa flutuante; pacote fora do pin com data de apuração
 - [ ] Nenhum `Guid.NewGuid()` — usar `Guid.CreateVersion7()` se IDs são necessários
 
 ---
@@ -242,9 +341,11 @@ prefira o tipo de instância resolvido por DI a métodos estáticos com estado g
 - `ai-agents-setup` — pacotes base MAF, DI, quick start
 - `ai-agents-mcp-tools` — consumir MCP servers externos em um agente MAF
 - `ai-agents-production` — middleware pipeline, `ResilientToolMiddleware`, segurança
-- [ModelContextProtocol C# SDK](https://github.com/modelcontextprotocol/csharp-sdk)
+- [ModelContextProtocol C# SDK](https://github.com/modelcontextprotocol/csharp-sdk) — `docs/concepts/filters.md`, `docs/concepts/identity/identity.md` (lidos 2026-09-08)
+- [MCP — versionamento da especificação](https://modelcontextprotocol.io/specification/versioning) e o changelog da revisão `2026-07-28` (lidos 2026-09-08)
+- [NuGet — ModelContextProtocol 2.2.0](https://www.nuget.org/packages/ModelContextProtocol/2.2.0) (publicado 2026-08-13)
 - [Expose Agent as MCP Server — MAF docs](https://learn.microsoft.com/en-us/agent-framework/agents/tools/local-mcp-tools)
 
 ---
 
-*MORPH-SPEC by Polymorphism Tech — ai-agents/mcp-server.md v1.0 (2026-05-19)*
+*MORPH-SPEC by Polymorphism Tech — ai-agents/mcp-server.md v2.0 (2026-09-08)*