Ajustes na documentação e remanejamento dos folders

.env.example

@@ -77,6 +77,7 @@ LANGFUSE_HOST=http://localhost:3005
 ENABLE_OTEL=false
 OTEL_EXPORTER_OTLP_ENDPOINT=
 OTEL_SERVICE_NAME=ai-agent-template
+ENABLE_LANGFUSE_OPENAI_AUTO_INSTRUMENTATION=true
 
 ###############################################################################
 # Analytics / Observer corporativo
@@ -165,3 +166,15 @@ MEMORY_MAX_SUMMARY_CHARS=6000
 MEMORY_SUMMARY_USE_LLM=true
 MEMORY_INJECT_RECENT_MESSAGES=true
 MEMORY_INJECT_SUMMARY=true
+
+###############################################################################
+# MCP Gateway
+###############################################################################
+# true = framework routes tool calls to the dedicated MCP Gateway.
+# false = framework calls MCP servers directly from mcp_servers.yaml.
+MCP_GATEWAY_ENABLED=true
+MCP_GATEWAY_URL=http://localhost:8300
+MCP_GATEWAY_TIMEOUT_SECONDS=60
+# MCP_GATEWAY_TOKEN=
+MCP_GATEWAY_AGENT_ID=telecom_contas
+MCP_GATEWAY_TENANT_ID=default

.idea/.gitignore

@@ -1,10 +0,0 @@
-# Default ignored files
-/shelf/
-/workspace.xml
-# Editor-based HTTP Client requests
-/httpRequests/
-# Environment-dependent path to Maven home directory
-/mavenHomeManager.xml
-# Datasource local storage ignored files
-/dataSources/
-/dataSources.local.xml

.idea/agent_platform_oci.iml

@@ -1,16 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<module type="JAVA_MODULE" version="4">
-  <component name="NewModuleRootManager" inherit-compiler-output="true">
-    <exclude-output />
-    <content url="file://$MODULE_DIR$" />
-    <orderEntry type="inheritedJdk" />
-    <orderEntry type="sourceFolder" forTests="false" />
-  </component>
-  <component name="TemplatesService">
-    <option name="TEMPLATE_FOLDERS">
-      <list>
-        <option value="$MODULE_DIR$/templates" />
-      </list>
-    </option>
-  </component>
-</module>

.idea/codeStyles/Project.xml

@@ -1,7 +0,0 @@
-<component name="ProjectCodeStyleConfiguration">
-  <code_scheme name="Project" version="173">
-    <ScalaCodeStyleSettings>
-      <option name="MULTILINE_STRING_CLOSING_QUOTES_ON_NEW_LINE" value="true" />
-    </ScalaCodeStyleSettings>
-  </code_scheme>
-</component>

.idea/codeStyles/codeStyleConfig.xml

@@ -1,5 +0,0 @@
-<component name="ProjectCodeStyleConfiguration">
-  <state>
-    <option name="PREFERRED_PROJECT_CODE_STYLE" value="Default" />
-  </state>
-</component>

.idea/modules.xml

@@ -1,8 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project version="4">
-  <component name="ProjectModuleManager">
-    <modules>
-      <module fileurl="file://$PROJECT_DIR$/.idea/agent_platform_oci.iml" filepath="$PROJECT_DIR$/.idea/agent_platform_oci.iml" />
-    </modules>
-  </component>
-</project>

.idea/vcs.xml

@@ -1,6 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project version="4">
-  <component name="VcsDirectoryMappings">
-    <mapping directory="" vcs="Git" />
-  </component>
-</project>

README.md

@@ -25,83 +25,83 @@ A documentação da Agent Platform OCI está organizada em SPECs/SDDs numeradas,
 
 >**/agent_platform_oci/specs**
 
-### SPEC-001 — Architecture
+### [SPEC-001 — Architecture](specs/SPEC-001-Architecture.md)
 
 Define a arquitetura geral da plataforma, seus componentes principais, estrutura de repositório, arquitetura lógica e física, contratos centrais, fluxo principal, requisitos não funcionais e critérios de aceite.
 
-### SPEC-002 — Agent Runtime
+### [SPEC-002 — Agent Runtime](specs/SPEC-002-Agent-Runtime.md)
 
 Descreve o runtime de execução conversacional dos agentes, incluindo LangGraph, estado, memória, checkpoints, roteamento, supervisor, BusinessContext, integração com MCP, RAG, eventos e tratamento de erros.
 
-### SPEC-003 — AI Gateway
+### [SPEC-003 — AI Gateway](specs/SPEC-003-AI-Gateway.md)
 
 Especifica o gateway responsável por centralizar chamadas de LLM e embeddings, incluindo contratos de request/response, profiles, providers, autenticação OCI, fallback, rate limit, métricas, segurança e observabilidade.
 
-### SPEC-004 — MCP Gateway
+### [SPEC-004 — MCP Gateway](specs/SPEC-004-MCP-Gateway.md)
 
 Define o modelo de integração com MCP, incluindo catálogo de tools, roteamento, execução, autorização, cache, retry, timeout, mapeamento de parâmetros, eventos, métricas e resposta padronizada das ferramentas.
 
-### SPEC-005 — Guardrails
+### [SPEC-005 — Guardrails](specs/SPEC-005-Guardrails.md)
 
 Descreve o modelo de guardrails da plataforma, cobrindo políticas de entrada, saída, tools, RAG e resposta final. Também define fases, modos de execução, tipos de guardrails, profiles LLM, códigos base, eventos, testes e critérios de aceite.
 
-### SPEC-006 — Evals
+### [SPEC-006 — Evals](specs/SPEC-006-Evals.md)
 
 Define a camada de avaliação da plataforma, incluindo avaliação online, avaliação offline, regressão, certificação, datasets, judges, métricas, CLI, API, persistência de resultados e publicação de evidências.
 
-### SPEC-007 — Observability
+### [SPEC-007 — Observability](specs/SPEC-007-Observability.md)
 
 Especifica o modelo de observabilidade, incluindo logs, traces, métricas, Langfuse, OpenTelemetry, eventos IC/NOC/GRL, dashboards, alertas, mascaramento de dados e geração de evidências operacionais.
 
-### SPEC-008 — Deployment
+### [SPEC-008 — Deployment](specs/SPEC-008-Deployment.md)
 
 Descreve o processo de empacotamento e implantação da plataforma, incluindo componentes deployáveis, pipeline CI/CD, Kubernetes/OKE, Docker, secrets, autenticação OCI, health checks, rollback, smoke tests e etapa de certificação.
 
-### SPEC-009 — Channel Gateway
+### [SPEC-009 — Channel Gateway](specs/SPEC-009-Channel-Gateway.md)
 
 Define o gateway de canais, responsável por normalizar payloads externos para o contrato canônico da plataforma e traduzir respostas para cada canal. Cobre modos de operação, idempotência, versionamento, segurança, erros e anti-patterns.
 
-### SPEC-010 — Agent Development
+### [SPEC-010 — Agent Development](specs/SPEC-010-Agent-Development.md)
 
 Descreve o padrão para desenvolvimento de agentes usando templates, configuração YAML, BusinessContext, MCP, guardrails, judges, RAG, memória, observabilidade e evals. Também diferencia responsabilidades do framework e do agente.
 
-### SPEC-011 — Governance Model
+### [SPEC-011 — Governance Model](specs/SPEC-011-Governance-Model.md)
 
 Define o modelo de governança da plataforma, incluindo ownership, papéis e responsabilidades, RACI, governança de agentes, prompts, guardrails, judges, modelos, MCP, datasets, processo de aprovação e evidências obrigatórias.
 
-### SPEC-012 — Canonical Contracts
+### [SPEC-012 — Canonical Contracts](specs/SPEC-012-Canonical-Contracts.md)
 
 Documenta os contratos canônicos da plataforma, como GatewayRequest, ChannelResponse, BusinessContext, AgentState, ToolInvocation, ToolResult, LLMRequest, LLMResponse, EvaluationRun e EventEnvelope. Também define regras de evolução desses contratos.
 
-### SPEC-013 — Versioning and Compatibility Model
+### [SPEC-013 — Versioning and Compatibility Model](specs/SPEC-013-Versioning-and-Compatibility-Model.md)
 
 Define o modelo de versionamento e compatibilidade da plataforma, incluindo Semantic Versioning, artefatos versionados, versionamento de contratos, matriz de compatibilidade, política de depreciação, migração e rollback.
 
-### SPEC-014 — Templates and Agent Creation Model
+### [SPEC-014 — Templates and Agent Creation Model](specs/SPEC-014-Templates-and-Agent-Creation-Model.md)
 
 Descreve os templates oficiais e o modelo de criação de agentes do zero. Explica o que pertence ao framework, o que pertence ao agente, a estrutura padrão e o passo a passo para copiar template, definir escopo, registrar agente, configurar rotas, tools, BusinessContext, prompts, datasets e testes.
 
-### SPEC-015 — Adoption and Eligibility Criteria
+### [SPEC-015 — Adoption and Eligibility Criteria](specs/SPEC-015-Adoption-and-Eligibility-Criteria.md)
 
 Define os critérios claros para adoção da plataforma, incluindo casos indicados, casos não indicados, critérios de entrada de negócio, arquitetura, segurança, qualidade, operação, processo de exceção e checklist de adoção.
 
-### SPEC-016 — Agent Development Lifecycle
+### [SPEC-016 — Agent Development Lifecycle](specs/SPEC-016-Agent-Development-Lifecycle.md)
 
 Descreve o ciclo de vida completo de desenvolvimento de agentes, desde discovery e definição de escopo até design, prompt, MCP, RAG, implementação, testes, avaliação, certificação, homologação e produção.
 
-### SPEC-017 — Release Management and CI/CD
+### [SPEC-017 — Release Management and CI/CD](specs/SPEC-017-Release-Management-and-CICD.md)
 
 Define o modelo de release e CI/CD, incluindo pipeline padrão, stages, artefatos de release, gates de qualidade, estratégia de rollback, erros comuns e critérios de aceite.
 
-### SPEC-018 — Security and Identity Model
+### [SPEC-018 — Security and Identity Model](specs/SPEC-018-Security-and-Identity-Model.md)
 
 Especifica o modelo de segurança e identidade da plataforma, cobrindo autenticação, Workload Identity, autorização, secrets, proteção de dados, segurança em MCP, segurança em canais, auditoria e critérios de aceite.
 
-### SPEC-019 — Evaluation and Certification Framework
+### [SPEC-019 — Evaluation and Certification Framework](specs/SPEC-019-Evaluation-and-Certification-Framework.md)
 
 Detalha o framework de avaliação e certificação, incluindo arquitetura de avaliação, métricas, datasets, EvaluationRun, CLI, processo de certificação, evidências obrigatórias e critérios de aceite.
 
-### SPEC-020 — Operational Readiness and SRE Model
+### [SPEC-020 — Operational Readiness and SRE Model](specs/SPEC-020-Operational-Readiness-and-SRE-Model.md)
 
 Define o modelo de readiness operacional e SRE da plataforma, incluindo componentes operados, health checks, readiness, SLOs, métricas, dashboards, alertas, runbooks, gestão de incidentes, capacidade e checklist de produção.
 
@@ -7862,6 +7862,64 @@ workflow concluído
 
 ## 17. Build e execução local
 
+Vamos subir a estrutura completa de um agente:
+
+```text
+Frontend (5173)
+↓
+Agent Gateway (9000)
+↓
+Agent Template Backend / Runtime (8000)
+↓
+MCP Gateway (8300)
+↓
+Telecom MCP Server (8100)
+Retail MCP Server (8200)
+```
+
+### Portas Oficiais
+
+| Componente | Porta |
+|------------|--------|
+| Frontend | 5173 |
+| Agent Gateway | 9000 |
+| Backend Runtime | 8000 |
+| MCP Gateway | 8300 |
+| Telecom MCP Server | 8100 |
+| Retail MCP Server | 8200 |
+
+### Variáveis Oficiais
+
+### Agent Template Backend
+
+ENABLE_MCP_TOOLS=true
+
+MCP_GATEWAY_ENABLED=true
+MCP_GATEWAY_URL=http://localhost:8300
+MCP_GATEWAY_TIMEOUT_SECONDS=60
+MCP_GATEWAY_AGENT_ID=telecom_contas
+MCP_GATEWAY_TENANT_ID=default
+
+### Agent Gateway
+
+DEFAULT_AGENT_BACKEND_URL=http://localhost:8000
+AGENT_GATEWAY_GOVERNANCE_CONFIG=config/gateway_governance.yaml
+
+### MCP Gateway
+
+MCP_GATEWAY_CONFIG_PATH=config/mcp_gateway.yaml
+
+### Ordem de Inicialização
+
+1. Telecom MCP Server
+2. Retail MCP Server
+3. MCP Gateway
+4. Agent Template Backend
+5. Agent Gateway
+6. Frontend
+
+---
+
 Na raiz do projeto:
 
 ```bash
@@ -7967,7 +8025,34 @@ servers:
 > Você pode customizar para subir todos os seus mcp servers.
 > Execute: **bash ./scripts/run_mcp_servers.sh**
 
-### 18.3. Testar tool pelo backend
+### 18.3. Subir o MCP Gateway
+
+```bash
+cd apps/mcp_gateway
+
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+
+export MCP_GATEWAY_CONFIG_PATH=config/mcp_gateway.yaml
+
+python -m uvicorn app.main:app --host 0.0.0.0 --port 8300 --reload
+```
+
+Validações:
+
+```bash
+curl http://localhost:8300/health
+curl http://localhost:8300/ready
+curl http://localhost:8300/v1/tools
+```
+
+Teste:
+
+curl -X POST http://localhost:8300/v1/tools/consultar_fatura/invoke
+
+
+### 18.4. Testar tool pelo backend
 
 Teste pelo backend, não diretamente pelo MCP. Assim você valida o caminho completo:
 
@@ -7992,7 +8077,7 @@ curl -X POST http://localhost:8000/debug/mcp/call/consultar_titulo_financeiro \
 
 >**Nota:** No projeto existe também uma interface visual para testar:
 
-### 18.4. Subir Frontend para testes
+### 18.5. Subir Frontend para testes
 
 Install before the [npm](https://nodejs.org/) and:
 
@@ -8007,7 +8092,7 @@ Abra http://localhost:5173.
 
 >**Nota:** O frontend está preparado para funcionar com o **Agent Gateway**. No projeto, consulte os capítulos 28 e 28.10 para experimentá-lo. Lembre-se apenas de trocar **Backend URL** para **http://localhost:8010** pois 8010 é a porta onde o **Agent Gateway** estará escutando.
 
-### 18.5. Como interpretar erros MCP
+### 18.6. Como interpretar erros MCP
 
 ```text
 Tool não encontrada         → tools.yaml ou nome da tool errado.
@@ -8017,6 +8102,32 @@ Parâmetro obrigatório ausente → identity.yaml ou mcp_parameter_mapping.yaml
 Timeout                     → MCP lento, endpoint errado, VPN, DNS ou sistema real indisponível.
 ```
 
+### 18.7. Subir Agent Gateway
+
+```bash
+cd apps/agent_gateway
+
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+
+export DEFAULT_AGENT_BACKEND_URL=http://localhost:8000
+export AGENT_GATEWAY_GOVERNANCE_CONFIG=config/gateway_governance.yaml
+
+python -m uvicorn app.main:app --host 0.0.0.0 --port 9000 --reload
+```
+
+Validações:
+
+```bash
+curl http://localhost:9000/health
+```
+
+Teste:
+
+curl -X POST http://localhost:9000/gateway/message
+
+
 ---
 
 ## 19. Build com Docker

README_en.md

@@ -24,85 +24,86 @@ The Agent Platform OCI documentation is organized into numbered SPECs/SDDs, each
 
 >**/agent_platform_oci/specs**
 
-### SPEC-001 — Architecture
+### [SPEC-001 — Architecture](specs/SPEC-001-Architecture.md)
 
-Defines the overall architecture of the platform, its main components, repository structure, logical and physical architecture, core contracts, main flow, non-functional requirements, and acceptance criteria.
+Defines the overall platform architecture, its main components, repository structure, logical and physical architecture, core contracts, primary flow, non-functional requirements, and acceptance criteria.
 
-### SPEC-002 — Agent Runtime
+### [SPEC-002 — Agent Runtime](specs/SPEC-002-Agent-Runtime.md)
 
-Describes the conversational execution runtime of the agents, including LangGraph, state, memory, checkpoints, routing, supervisor, BusinessContext, MCP integration, RAG, events, and error handling.
+Describes the conversational execution runtime for agents, including LangGraph, state management, memory, checkpoints, routing, supervisor, BusinessContext, MCP integration, RAG, events, and error handling.
 
-### SPEC-003 — AI Gateway
+### [SPEC-003 — AI Gateway](specs/SPEC-003-AI-Gateway.md)
 
 Specifies the gateway responsible for centralizing LLM and embedding calls, including request/response contracts, profiles, providers, OCI authentication, fallback, rate limiting, metrics, security, and observability.
 
-### SPEC-004 — MCP Gateway
+### [SPEC-004 — MCP Gateway](specs/SPEC-004-MCP-Gateway.md)
 
-Defines the MCP integration model, including tool catalog, routing, execution, authorization, cache, retry, timeout, parameter mapping, events, metrics, and standardized tool responses.
+Defines the MCP integration model, including the tool catalog, routing, execution, authorization, caching, retries, timeouts, parameter mapping, events, metrics, and standardized tool responses.
 
-### SPEC-005 — Guardrails
+### [SPEC-005 — Guardrails](specs/SPEC-005-Guardrails.md)
 
-Describes the platform guardrails model, covering input, output, tools, RAG, and final response policies. It also defines phases, execution modes, guardrail types, LLM profiles, base codes, events, tests, and acceptance criteria.
+Describes the platform guardrail model, covering input, output, tool, RAG, and final response policies. It also defines phases, execution modes, guardrail types, LLM profiles, base codes, events, tests, and acceptance criteria.
 
-### SPEC-006 — Evals
+### [SPEC-006 — Evals](specs/SPEC-006-Evals.md)
 
-Defines the platform evaluation layer, including online evaluation, offline evaluation, regression, certification, datasets, judges, metrics, CLI, API, result persistence, and evidence publication.
+Defines the platform evaluation layer, including online evaluation, offline evaluation, regression testing, certification, datasets, judges, metrics, CLI, API, result persistence, and evidence publication.
 
-### SPEC-007 — Observability
+### [SPEC-007 — Observability](specs/SPEC-007-Observability.md)
 
 Specifies the observability model, including logs, traces, metrics, Langfuse, OpenTelemetry, IC/NOC/GRL events, dashboards, alerts, data masking, and operational evidence generation.
 
-### SPEC-008 — Deployment
+### [SPEC-008 — Deployment](specs/SPEC-008-Deployment.md)
 
-Describes the platform packaging and deployment process, including deployable components, CI/CD pipeline, Kubernetes/OKE, Docker, secrets, OCI authentication, health checks, rollback, smoke tests, and certification stage.
+Describes the platform packaging and deployment process, including deployable components, CI/CD pipelines, Kubernetes/OKE, Docker, secrets, OCI authentication, health checks, rollback, smoke tests, and certification stages.
 
-### SPEC-009 — Channel Gateway
+### [SPEC-009 — Channel Gateway](specs/SPEC-009-Channel-Gateway.md)
 
-Defines the channel gateway, responsible for normalizing external payloads into the platform’s canonical contract and translating responses for each channel. It covers operation modes, idempotency, versioning, security, errors, and anti-patterns.
+Defines the channel gateway responsible for normalizing external payloads into the platform's canonical contract and translating responses for each channel. Covers operating modes, idempotency, versioning, security, errors, and anti-patterns.
 
-### SPEC-010 — Agent Development
+### [SPEC-010 — Agent Development](specs/SPEC-010-Agent-Development.md)
 
-Describes the standard for developing agents using templates, YAML configuration, BusinessContext, MCP, guardrails, judges, RAG, memory, observability, and evals. It also differentiates the responsibilities of the framework and the agent.
+Describes the standard for agent development using templates, YAML configuration, BusinessContext, MCP, guardrails, judges, RAG, memory, observability, and evaluations. It also differentiates framework and agent responsibilities.
 
-### SPEC-011 — Governance Model
+### [SPEC-011 — Governance Model](specs/SPEC-011-Governance-Model.md)
 
-Defines the platform governance model, including ownership, roles and responsibilities, RACI, governance of agents, prompts, guardrails, judges, models, MCP, datasets, approval process, and mandatory evidence.
+Defines the platform governance model, including ownership, roles and responsibilities, RACI, agent governance, prompts, guardrails, judges, models, MCP, datasets, approval processes, and mandatory evidence.
 
-### SPEC-012 — Canonical Contracts
+### [SPEC-012 — Canonical Contracts](specs/SPEC-012-Canonical-Contracts.md)
 
-Documents the platform’s canonical contracts, such as GatewayRequest, ChannelResponse, BusinessContext, AgentState, ToolInvocation, ToolResult, LLMRequest, LLMResponse, EvaluationRun, and EventEnvelope. It also defines rules for evolving these contracts.
+Documents the platform's canonical contracts, including GatewayRequest, ChannelResponse, BusinessContext, AgentState, ToolInvocation, ToolResult, LLMRequest, LLMResponse, EvaluationRun, and EventEnvelope. It also defines contract evolution rules.
 
-### SPEC-013 — Versioning and Compatibility Model
+### [SPEC-013 — Versioning and Compatibility Model](specs/SPEC-013-Versioning-and-Compatibility-Model.md)
 
-Defines the platform versioning and compatibility model, including Semantic Versioning, versioned artifacts, contract versioning, compatibility matrix, deprecation policy, migration, and rollback.
+Defines the platform versioning and compatibility model, including Semantic Versioning, versioned artifacts, contract versioning, compatibility matrices, deprecation policies, migration, and rollback.
 
-### SPEC-014 — Templates and Agent Creation Model
+### [SPEC-014 — Templates and Agent Creation Model](specs/SPEC-014-Templates-and-Agent-Creation-Model.md)
 
-Describes the official templates and the model for creating agents from scratch. It explains what belongs to the framework, what belongs to the agent, the standard structure, and the step-by-step process to copy a template, define scope, register the agent, configure routes, tools, BusinessContext, prompts, datasets, and tests.
+Describes the official templates and the agent creation model from scratch. Explains what belongs to the framework, what belongs to the agent, the standard structure, and the step-by-step process for copying templates, defining scope, registering agents, configuring routes, tools, BusinessContext, prompts, datasets, and tests.
 
-### SPEC-015 — Adoption and Eligibility Criteria
+### [SPEC-015 — Adoption and Eligibility Criteria](specs/SPEC-015-Adoption-and-Eligibility-Criteria.md)
 
-Defines clear criteria for adopting the platform, including recommended use cases, non-recommended use cases, business entry criteria, architecture, security, quality, operation, exception process, and adoption checklist.
+Defines clear platform adoption criteria, including recommended and non-recommended use cases, business entry criteria, architecture, security, quality, operations, exception processes, and adoption checklists.
 
-### SPEC-016 — Agent Development Lifecycle
+### [SPEC-016 — Agent Development Lifecycle](specs/SPEC-016-Agent-Development-Lifecycle.md)
 
-Describes the complete agent development lifecycle, from discovery and scope definition to design, prompt, MCP, RAG, implementation, testing, evaluation, certification, homologation, and production.
+Describes the complete agent development lifecycle, from discovery and scope definition through design, prompting, MCP, RAG, implementation, testing, evaluation, certification, validation, and production.
 
-### SPEC-017 — Release Management and CI/CD
+### [SPEC-017 — Release Management and CI/CD](specs/SPEC-017-Release-Management-and-CICD.md)
 
-Defines the release and CI/CD model, including the standard pipeline, stages, release artifacts, quality gates, rollback strategy, common errors, and acceptance criteria.
+Defines the release and CI/CD model, including standard pipelines, stages, release artifacts, quality gates, rollback strategies, common errors, and acceptance criteria.
 
-### SPEC-018 — Security and Identity Model
+### [SPEC-018 — Security and Identity Model](specs/SPEC-018-Security-and-Identity-Model.md)
 
 Specifies the platform security and identity model, covering authentication, Workload Identity, authorization, secrets, data protection, MCP security, channel security, auditing, and acceptance criteria.
 
-### SPEC-019 — Evaluation and Certification Framework
+### [SPEC-019 — Evaluation and Certification Framework](specs/SPEC-019-Evaluation-and-Certification-Framework.md)
 
-Details the evaluation and certification framework, including evaluation architecture, metrics, datasets, EvaluationRun, CLI, certification process, mandatory evidence, and acceptance criteria.
+Details the evaluation and certification framework, including evaluation architecture, metrics, datasets, EvaluationRun, CLI, certification processes, mandatory evidence, and acceptance criteria.
 
-### SPEC-020 — Operational Readiness and SRE Model
+### [SPEC-020 — Operational Readiness and SRE Model](specs/SPEC-020-Operational-Readiness-and-SRE-Model.md)
+
+Defines the platform operational readiness and SRE model, including managed components, health checks, readiness, SLOs, metrics, dashboards, alerts, runbooks, incident management, capacity planning, and production checklists.
 
-Defines the platform operational readiness and SRE model, including operated components, health checks, readiness, SLOs, metrics, dashboards, alerts, runbooks, incident management, capacity, and production checklist.
 
 ---
 
@@ -7766,22 +7767,80 @@ workflow completed
 
 ---
 
-## 17. Build and local execution
+## 17. Local Build and Execution
 
-At the root of the project:
+Let's bring up the complete agent stack:
+
+```text
+Frontend (5173)
+↓
+Agent Gateway (9000)
+↓
+Agent Template Backend / Runtime (8000)
+↓
+MCP Gateway (8300)
+↓
+Telecom MCP Server (8100)
+Retail MCP Server (8200)
+```
+
+### Official Ports
+
+| Component | Port |
+|------------|--------|
+| Frontend | 5173 |
+| Agent Gateway | 9000 |
+| Backend Runtime | 8000 |
+| MCP Gateway | 8300 |
+| Telecom MCP Server | 8100 |
+| Retail MCP Server | 8200 |
+
+### Official Variables
+
+### Agent Template Backend
+
+ENABLE_MCP_TOOLS=true
+
+MCP_GATEWAY_ENABLED=true
+MCP_GATEWAY_URL=http://localhost:8300
+MCP_GATEWAY_TIMEOUT_SECONDS=60
+MCP_GATEWAY_AGENT_ID=telecom_contas
+MCP_GATEWAY_TENANT_ID=default
+
+### Agent Gateway
+
+DEFAULT_AGENT_BACKEND_URL=http://localhost:8000
+AGENT_GATEWAY_GOVERNANCE_CONFIG=config/gateway_governance.yaml
+
+### MCP Gateway
+
+MCP_GATEWAY_CONFIG_PATH=config/mcp_gateway.yaml
+
+### Startup Order
+
+1. Telecom MCP Server
+2. Retail MCP Server
+3. MCP Gateway
+4. Agent Template Backend
+5. Agent Gateway
+6. Frontend
+
+---
+
+From the project root:
 
 ```bash
 cd agent_platform_oci
 python -m venv .venv
 ```
 
-### 17.1. Before the commands: what does it mean to upload the backend?
+### 17.1. Before the commands: what does starting the backend mean?
 
-Bringing up the backend means starting the API that receives messages, normalizes the channel, resolves identity, opens a session, executes the workflow, and returns a response.
+Starting the backend means launching the API that receives messages, normalizes the channel, resolves identity, opens a session, executes the workflow, and returns a response.
 
-It can be uploaded even without a real MCP, as long as the configuration is in mock or the tools are not required for the test.
+It can be started even without a real MCP, as long as the configuration is in mock mode or the tools are not required for the test.
 
-### 17.2. Run local backend
+### 17.2. Run the Backend Locally
 
 Inside `agent_template_backend`:
 
@@ -7800,7 +7859,7 @@ Windows PowerShell:
 python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
 ```
 
-### 17.3. Immediate validations
+### 17.3. Immediate Validations
 
 Check health:
 
@@ -7820,11 +7879,11 @@ List known MCP tools:
 curl http://localhost:8000/debug/mcp/tools
 ```
 
-### 17.4. How to interpret the result
+### 17.4. How to Interpret the Result
 
 ```text
-/health ok         → API is up.
+/health ok         → API started successfully.
-/agents lista      → agents.yaml was loaded.
+/agents lists agents      → agents.yaml was loaded.
 /debug/mcp/tools   → tools.yaml and mcp_servers.yaml were loaded.
 ```
 
@@ -7832,25 +7891,25 @@ If `/health` works but`/agents` does not list the agent, the problem is probably
 
 ---
 
-## 18. Uploading MCP Servers
+## 18. Starting MCP Servers
 
-### 18.1. Before the commands: when do I need to upload MCP?
+### 18.1. Before the commands: when do I need to start MCP?
 
-You need to upload MCP when the chosen intent uses `mcp_tools` and the agent depends on these tools to respond.
+You need to start MCP when the selected intent uses `mcp_tools` and the agent depends on those tools to respond.
 
-You don't need to upload MCP just to test:
+You do not need MCP running to test only:
 
 ```text
 health check
 agent registration
 basic routing
 mock LLM without tools
-simple conversational flow without external query
+simple conversational flow without external lookup
 ```
 
-### 18.2. Upload local MCP Server
+### 18.2. Start a Local MCP Server
 
-If the MCP Servers are separate Python processes, upload each one on a different port.
+If the MCP Servers are separate Python processes, start each one on a different port.
 
 Example:
 
@@ -7868,14 +7927,41 @@ financeiro:
     endpoint: http://localhost:8300/mcp
 ```
 
-> **Note:** The**/scripts/ folder** has automated mcp server startup scripts for educational purposes.
+> **Note:** The **/scripts/** folder contains automated MCP Server startup scripts for demonstration and educational purposes.
-> The **/agent_template_backend folder** has 2 mcp servers configured, one on port 8100 and the other on 8200. These services are ready and configured to run if you want to test the circuit.
+> The **/agent_template_backend** folder includes two MCP Servers already configured, one running on port **8100** and the other on port **8200**. These services are ready to run if you want to test the full flow.
-> You can customize it to upload all your mcp servers.
+> You can customize the setup to start all of your MCP Servers.
 > Run: **bash ./scripts/run_mcp_servers.sh**
 
-### 18.3. Test tool through the backend
+### 18.3. Start the MCP Gateway
 
-Test through the backend, not directly through the MCP. This way, you validate the complete path:
+```bash
+cd apps/mcp_gateway
+
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+
+export MCP_GATEWAY_CONFIG_PATH=config/mcp_gateway.yaml
+
+python -m uvicorn app.main:app --host 0.0.0.0 --port 8300 --reload
+```
+
+Validations:
+
+```bash
+curl http://localhost:8300/health
+curl http://localhost:8300/ready
+curl http://localhost:8300/v1/tools
+```
+
+Test:
+
+curl -X POST http://localhost:8300/v1/tools/consultar_fatura/invoke
+
+
+### 18.4. Test a Tool Through the Backend
+
+Test through the backend, not directly through MCP. This validates the full path:
 
 ```text
 backend → MCP Tool Router → MCP Server → response
@@ -7896,9 +7982,11 @@ curl -X POST http://localhost:8000/debug/mcp/call/consultar_titulo_financeiro \
   }'
 ```
 
-> **Note:** In the project, there is also a visual interface for testing:
+> **Note:** The project also includes a visual interface for testing:
 
-### 18.4. Upload Frontend for testing
+### 18.5. Start the Frontend for Testing
+
+Install before the [npm](https://nodejs.org/) and:
 
 ```bash
 cd agent_platform_oci
@@ -7909,18 +7997,45 @@ python -m http.server 5173
 Open http://localhost:5173.
 
 
-> **Note:** The frontend is ready to work with the **Agent Gateway**. In the project, see chapters 28 and 28.10 to try it out. Just remember to change the **Backend URL** to **http://localhost:8010** because 8010 is the port where the **Agent Gateway** will be listening.
+> **Note:** The frontend is designed to work with the **Agent Gateway**. In the project documentation, see chapters 28 and 28.10 for usage examples. Just remember to change **Backend URL** to **http://localhost:8010**, as 8010 is the port where the **Agent Gateway** will be listening.
 
-### 18.5. How to interpret MCP errors
+### 18.6. How to Interpret MCP Errors
 
 ```text
-Tool not found         → tools.yaml or wrong tool name.
+Tool not found         → tools.yaml or tool name is incorrect.
-Server not found     → mcp_servers.yaml does not have the mcp_server indicated by the tool.
+Server not found     → mcp_servers.yaml does not contain the MCP server referenced by the tool.
-Connection refused          → MCP Server is not running or wrong port.
+Connection refused          → MCP Server is not running or the port is incorrect.
-Required parameter missing → identity.yaml or mcp_parameter_mapping.yaml incorrect.
+Missing required parameter → identity.yaml or mcp_parameter_mapping.yaml is incorrect.
-Timeout                     → Slow MCP, wrong endpoint, VPN, DNS or real system unavailable.
+Timeout                     → Slow MCP, wrong endpoint, VPN, DNS, or target system unavailable.
 ```
 
+### 18.7. Start the Agent Gateway
+
+```bash
+cd apps/agent_gateway
+
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+
+export DEFAULT_AGENT_BACKEND_URL=http://localhost:8000
+export AGENT_GATEWAY_GOVERNANCE_CONFIG=config/gateway_governance.yaml
+
+python -m uvicorn app.main:app --host 0.0.0.0 --port 9000 --reload
+```
+
+Validations:
+
+```bash
+curl http://localhost:9000/health
+```
+
+Test:
+
+curl -X POST http://localhost:9000/gateway/message
+
+
+
 ---
 
 ## 19. Build with Docker

apps/agent_gateway/config/backends.yaml

@@ -2,7 +2,7 @@ default_backend: contas
 
 backends:
   contas:
-    url: http://localhost:8001
+    url: http://localhost:8000
     description: Backend responsável por faturas, contas, pagamentos, consumo, segunda via e contestação.
     domains: [contas, fatura, pagamento, consumo, contestacao]
     keywords: [fatura, conta, boleto, pagamento, consumo, segunda via, contestar, contestação, valor, cobrança]
@@ -14,7 +14,7 @@ backends:
     default_agent_id: telecom_contas
 
   ofertas:
-    url: http://localhost:8002
+    url: http://localhost:8001
     description: Backend responsável por ofertas, planos, upgrades, retenção e contratação.
     domains: [ofertas, planos, retenção, contratação]
     keywords: [oferta, plano, contratar, upgrade, desconto, promoção, pacote, retenção, cancelar serviço]
@@ -26,7 +26,7 @@ backends:
     default_agent_id: telecom_ofertas
 
   suporte:
-    url: http://localhost:8003
+    url: http://localhost:8002
     description: Backend responsável por suporte técnico, falhas, rede, internet e atendimento operacional.
     domains: [suporte, técnico, rede, internet]
     keywords: [internet, sinal, rede, suporte, técnico, problema, falha, sem conexão, modem]

apps/ai_gateway/Dockerfile

@@ -1,7 +0,0 @@
-FROM python:3.11-slim
-WORKDIR /app
-COPY apps/ai_gateway/requirements.txt /app/requirements.txt
-RUN pip install --no-cache-dir -r /app/requirements.txt
-COPY apps/ai_gateway /app
-EXPOSE 9100
-CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "9100"]

apps/ai_gateway/README.md

@@ -1,18 +0,0 @@
-# AI Gateway
-
-Camada desacoplada para abstração, roteamento, controle e governança de chamadas LLM.
-
-Este componente não substitui o Agent Runtime. Ele centraliza políticas de modelo, seleção de provider, fallback, telemetria e controles corporativos.
-
-## Rotas
-
-- `GET /health`
-- `GET /models`
-- `POST /v1/chat/completions`
-
-## Execução local
-
-```bash
-cd apps/ai_gateway
-uvicorn app.main:app --host 0.0.0.0 --port 9100 --reload
-```

apps/ai_gateway/app/main.py

@@ -1,81 +0,0 @@
-from __future__ import annotations
-
-import os
-from typing import Any, Literal
-
-import httpx
-from fastapi import FastAPI, HTTPException
-from pydantic import BaseModel, Field
-
-
-class Message(BaseModel):
-    role: Literal["system", "user", "assistant", "tool"]
-    content: str | list[Any] | None = None
-
-
-class ChatCompletionRequest(BaseModel):
-    model: str | None = None
-    messages: list[Message]
-    temperature: float | None = None
-    max_tokens: int | None = None
-    metadata: dict[str, Any] = Field(default_factory=dict)
-
-
-class ModelRoute(BaseModel):
-    provider: str
-    model: str
-    base_url: str | None = None
-
-
-app = FastAPI(title="Agent Framework OCI - AI Gateway", version="0.1.0")
-
-
-def resolve_route(requested_model: str | None, metadata: dict[str, Any]) -> ModelRoute:
-    provider = metadata.get("provider") or os.getenv("AI_GATEWAY_DEFAULT_PROVIDER", "oci_openai")
-    model = requested_model or metadata.get("profile_model") or os.getenv("AI_GATEWAY_DEFAULT_MODEL", "openai.gpt-4.1")
-    base_url = os.getenv("AI_GATEWAY_OPENAI_COMPAT_BASE_URL")
-    return ModelRoute(provider=provider, model=model, base_url=base_url)
-
-
-@app.get("/health")
-def health() -> dict[str, Any]:
-    return {"status": "ok", "component": "ai_gateway"}
-
-
-@app.get("/models")
-def models() -> dict[str, Any]:
-    return {
-        "default_provider": os.getenv("AI_GATEWAY_DEFAULT_PROVIDER", "oci_openai"),
-        "default_model": os.getenv("AI_GATEWAY_DEFAULT_MODEL", "openai.gpt-4.1"),
-        "purpose": "model routing, policy control and LLM abstraction",
-    }
-
-
-@app.post("/v1/chat/completions")
-async def chat_completions(payload: ChatCompletionRequest) -> dict[str, Any]:
-    route = resolve_route(payload.model, payload.metadata)
-    # Safe default: when no upstream is configured, return route decision only.
-    # Production deployments should configure AI_GATEWAY_OPENAI_COMPAT_BASE_URL and credentials.
-    if not route.base_url:
-        return {
-            "gateway": "ai_gateway",
-            "mode": "dry_run",
-            "route": route.model_dump(),
-            "message": "No upstream base URL configured. Set AI_GATEWAY_OPENAI_COMPAT_BASE_URL to proxy requests.",
-        }
-
-    api_key = os.getenv("AI_GATEWAY_API_KEY") or os.getenv("OCI_GENAI_API_KEY") or os.getenv("OPENAI_API_KEY")
-    headers = {"Authorization": f"Bearer {api_key}"} if api_key else {}
-    body = payload.model_dump(exclude_none=True)
-    body["model"] = route.model
-    try:
-        async with httpx.AsyncClient(timeout=float(os.getenv("AI_GATEWAY_TIMEOUT_SECONDS", "60"))) as client:
-            resp = await client.post(f"{route.base_url.rstrip('/')}/chat/completions", json=body, headers=headers)
-            resp.raise_for_status()
-            data = resp.json()
-            if isinstance(data, dict):
-                data.setdefault("gateway", "ai_gateway")
-                data.setdefault("route", route.model_dump())
-            return data
-    except httpx.HTTPError as exc:
-        raise HTTPException(status_code=502, detail=f"AI upstream request failed: {exc}") from exc

apps/ai_gateway/requirements.txt

@@ -1,5 +0,0 @@
-fastapi>=0.111
-uvicorn[standard]>=0.30
-pydantic>=2
-httpx>=0.27
-PyYAML>=6

apps/mcp_gateway/Dockerfile

@@ -1,7 +1,15 @@
-FROM python:3.11-slim
+FROM python:3.12-slim
+
 WORKDIR /app
+
 COPY apps/mcp_gateway/requirements.txt /app/requirements.txt
 RUN pip install --no-cache-dir -r /app/requirements.txt
-COPY apps/mcp_gateway /app
+
-EXPOSE 9200
+COPY apps/mcp_gateway/app /app/app
-CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "9200"]
+COPY apps/mcp_gateway/config /app/config
+
+ENV MCP_GATEWAY_CONFIG_PATH=/app/config/mcp_gateway.yaml
+
+EXPOSE 8300
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8300"]

apps/mcp_gateway/app/__init__.py

@@ -0,0 +1 @@
+

apps/mcp_gateway/app/main.py

@@ -1,74 +1,232 @@
 from __future__ import annotations
 
+import asyncio
+import hashlib
+import json
 import os
+import time
 from pathlib import Path
 from typing import Any
 
 import httpx
 import yaml
-from fastapi import FastAPI, HTTPException
+from fastapi import FastAPI, Header, HTTPException
 from pydantic import BaseModel, Field
 
 
-class ToolInvokeRequest(BaseModel):
+class BusinessContext(BaseModel):
+    customer_key: str | None = None
+    contract_key: str | None = None
+    interaction_key: str | None = None
+    account_key: str | None = None
+    resource_key: str | None = None
+    session_key: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ToolInvocation(BaseModel):
+    tenant_id: str = "default"
+    agent_id: str
+    channel: str | None = None
+    tool_name: str
     arguments: dict[str, Any] = Field(default_factory=dict)
-    context: dict[str, Any] = Field(default_factory=dict)
+    business_context: BusinessContext = Field(default_factory=BusinessContext)
+    metadata: dict[str, Any] = Field(default_factory=dict)
 
 
-app = FastAPI(title="Agent Framework OCI - MCP Gateway", version="0.1.0")
+class ToolResult(BaseModel):
+    tool_name: str
+    version: str | None = None
+    ok: bool
+    data: Any = None
+    error: str | None = None
+    cache: dict[str, Any] = Field(default_factory=dict)
+    latency_ms: int = 0
+    metadata: dict[str, Any] = Field(default_factory=dict)
 
 
 def load_config() -> dict[str, Any]:
-    config_path = Path(os.getenv("MCP_GATEWAY_CONFIG", "config/mcp_servers.yaml"))
+    path = Path(os.getenv("MCP_GATEWAY_CONFIG_PATH", "config/mcp_gateway.yaml"))
-    if not config_path.exists():
+    return yaml.safe_load(path.read_text(encoding="utf-8")) or {}
-        return {"servers": {}}
-    return yaml.safe_load(config_path.read_text()) or {"servers": {}}
 
 
-def find_tool(tool_name: str) -> tuple[str, dict[str, Any]] | None:
+config = load_config()
-    cfg = load_config()
+cache: dict[str, tuple[float, Any]] = {}
-    for server_name, server in (cfg.get("servers") or {}).items():
+app = FastAPI(title="Agent Platform OCI - MCP Gateway", version="1.0.0")
-        if tool_name in (server.get("tools") or []):
+
-            return server_name, server
+
-    return None
+def audit(name: str, payload: dict[str, Any]) -> None:
+    print(json.dumps({"event": name, **payload}, ensure_ascii=False, default=str))
+
+
+def auth_check(authorization: str | None) -> None:
+    auth = config.get("auth") or {}
+    if not auth.get("enabled", False):
+        return
+    if not authorization or not authorization.lower().startswith("bearer "):
+        raise HTTPException(status_code=401, detail="Missing MCP Gateway bearer token")
+    token = authorization.split(" ", 1)[1]
+    if token not in (auth.get("static_tokens") or {}):
+        raise HTTPException(status_code=403, detail="Invalid MCP Gateway token")
+
+
+def map_arguments(tool_name: str, args: dict[str, Any], bc: dict[str, Any]) -> dict[str, Any]:
+    result = dict(args or {})
+    for source, target in ((config.get("parameter_mapping") or {}).get(tool_name) or {}).items():
+        if bc.get(source) is not None and target not in result:
+            result[target] = bc[source]
+    return result
+
+
+def cache_key(tenant_id: str, agent_id: str, tool_name: str, version: str, args: dict[str, Any]) -> str:
+    digest = hashlib.sha256(json.dumps(args, sort_keys=True, ensure_ascii=False, default=str).encode()).hexdigest()
+    return f"mcp:{tenant_id}:{agent_id}:{tool_name}:{version}:{digest}"
+
+
+async def post_with_retry(url: str, payload: dict[str, Any], timeout: int, retry: dict[str, Any]) -> Any:
+    attempts = int(retry.get("max_attempts", 1)) if retry.get("enabled", False) else 1
+    backoff_ms = int(retry.get("backoff_ms", 250))
+    last_exc: Exception | None = None
+    for attempt in range(attempts):
+        try:
+            async with httpx.AsyncClient(timeout=timeout) as client:
+                resp = await client.post(url, json=payload)
+                resp.raise_for_status()
+                return resp.json()
+        except Exception as exc:
+            last_exc = exc
+            if attempt < attempts - 1:
+                await asyncio.sleep(backoff_ms / 1000)
+    raise RuntimeError(str(last_exc))
+
+
+def build_server_payload(tool_name: str, args: dict[str, Any], server: dict[str, Any], tool: dict[str, Any]) -> dict[str, Any]:
+    """Builds the payload expected by the downstream MCP server.
+
+    The example servers under mcp/servers expose the framework legacy contract:
+    POST /mcp/tools/call {tool_name, arguments}.  Some mocks expose direct
+    tool endpoints that accept only the argument object.  The gateway supports
+    both shapes through the server/tool config.
+    """
+    protocol = str(tool.get("protocol") or server.get("protocol") or "legacy_http")
+    if protocol in {"legacy_http", "framework_http"}:
+        return {"tool_name": tool_name, "arguments": args or {}}
+    return args or {}
+
+
+def normalize_server_response(data: Any) -> tuple[bool, Any, str | None, dict[str, Any]]:
+    if isinstance(data, dict) and ("ok" in data or "result" in data or "error" in data):
+        ok = bool(data.get("ok", not data.get("error")))
+        return ok, data.get("result", data.get("data")), data.get("error"), data.get("metadata") or {}
+    return True, data, None, {}
 
 
 @app.get("/health")
-def health() -> dict[str, Any]:
+async def health():
-    return {"status": "ok", "component": "mcp_gateway"}
+    return {"status": "ok", "service": "mcp_gateway"}
 
 
-@app.get("/tools")
+@app.get("/ready")
-def tools() -> dict[str, Any]:
+async def ready():
-    cfg = load_config()
+    enabled_tools = [k for k, v in (config.get("tools") or {}).items() if v.get("enabled", True)]
-    result = []
+    return {"status": "ready", "tools": enabled_tools}
-    for server_name, server in (cfg.get("servers") or {}).items():
-        for tool in server.get("tools") or []:
-            result.append({"name": tool, "server": server_name})
-    return {"tools": result}
 
 
-@app.post("/tools/{tool_name}/invoke")
+@app.get("/v1/tools")
-async def invoke_tool(tool_name: str, payload: ToolInvokeRequest) -> dict[str, Any]:
+async def tools():
-    found = find_tool(tool_name)
+    return {"tools": [{"name": name, **cfg} for name, cfg in (config.get("tools") or {}).items()]}
-    if not found:
+
-        raise HTTPException(status_code=404, detail=f"Tool not registered in MCP Gateway: {tool_name}")
+
-    server_name, server = found
+@app.get("/v1/tools/{tool_name}")
-    base_url = server.get("base_url")
+async def tool_detail(tool_name: str):
-    if not base_url:
+    tool = (config.get("tools") or {}).get(tool_name)
-        raise HTTPException(status_code=500, detail=f"Server {server_name} has no base_url")
+    if not tool:
+        raise HTTPException(status_code=404, detail=f"Tool not found: {tool_name}")
+    return {"name": tool_name, **tool}
+
+
+@app.post("/v1/tools/{tool_name}/invoke", response_model=ToolResult)
+async def invoke(tool_name: str, invocation: ToolInvocation, authorization: str | None = Header(default=None)):
+    started = time.perf_counter()
+    auth_check(authorization)
+
+    tool = (config.get("tools") or {}).get(tool_name)
+    if not tool or not tool.get("enabled", True):
+        raise HTTPException(status_code=404, detail=f"Tool not found or disabled: {tool_name}")
+
+    if invocation.tool_name != tool_name:
+        raise HTTPException(status_code=422, detail="Path tool_name and body tool_name differ")
+
+    allowed_agents = tool.get("allowed_agents") or []
+    if allowed_agents and invocation.agent_id not in allowed_agents:
+        raise HTTPException(status_code=403, detail=f"Agent not allowed: {invocation.agent_id}")
+
+    allowed_channels = tool.get("allowed_channels") or []
+    if invocation.channel and allowed_channels and invocation.channel not in allowed_channels:
+        raise HTTPException(status_code=403, detail=f"Channel not allowed: {invocation.channel}")
+
+    bc = invocation.business_context.model_dump()
+    missing = [k for k in tool.get("required_business_keys", []) if not bc.get(k)]
+    if missing:
+        raise HTTPException(status_code=422, detail={"missing_business_keys": missing})
+
+    version = str(tool.get("version", "1.0.0"))
+    args = map_arguments(tool_name, invocation.arguments, bc)
+
+    ttl = int(tool.get("cache_ttl_seconds", 0) or 0)
+    ck = None
+    if tool.get("idempotent", False) and ttl > 0:
+        ck = cache_key(invocation.tenant_id, invocation.agent_id, tool_name, version, args)
+        cached = cache.get(ck)
+        if cached and cached[0] > time.time():
+            audit("mcp.cache.hit", {"tool": tool_name, "agent_id": invocation.agent_id})
+            return ToolResult(
+                tool_name=tool_name,
+                version=version,
+                ok=True,
+                data=cached[1],
+                cache={"hit": True, "key": ck, "ttl_seconds": ttl},
+                latency_ms=int((time.perf_counter() - started) * 1000),
+            )
+
+    server = (config.get("servers") or {}).get(tool.get("server"))
+    if not server or not server.get("enabled", True):
+        raise HTTPException(status_code=503, detail=f"MCP server unavailable: {tool.get('server')}")
+
+    url = f"{server['url'].rstrip('/')}{tool.get('endpoint')}"
+    audit("mcp.tool.started", {"tool": tool_name, "version": version, "agent_id": invocation.agent_id, "server": tool.get("server")})
 
-    # Conventional endpoint. Concrete MCP servers may adapt this via an adapter later.
-    url = f"{base_url.rstrip('/')}/tools/{tool_name}/invoke"
     try:
-        async with httpx.AsyncClient(timeout=float(os.getenv("MCP_GATEWAY_TIMEOUT_SECONDS", "30"))) as client:
+        raw_data = await post_with_retry(
-            resp = await client.post(url, json=payload.model_dump())
+            url=url,
-            resp.raise_for_status()
+            payload=build_server_payload(tool_name, args, server, tool),
-            data = resp.json()
+            timeout=int(tool.get("timeout_seconds") or server.get("timeout_seconds") or 30),
-            if isinstance(data, dict):
+            retry=tool.get("retry") or {},
-                data.setdefault("gateway", "mcp_gateway")
+        )
-                data.setdefault("server", server_name)
+        ok, data, error, server_metadata = normalize_server_response(raw_data)
-                data.setdefault("tool", tool_name)
+        if ck and ttl > 0 and ok:
-            return data
+            cache[ck] = (time.time() + ttl, data)
-    except httpx.HTTPError as exc:
+
-        raise HTTPException(status_code=502, detail=f"MCP upstream request failed: {exc}") from exc
+        latency_ms = int((time.perf_counter() - started) * 1000)
+        audit("mcp.tool.completed", {"tool": tool_name, "latency_ms": latency_ms, "ok": ok})
+        return ToolResult(
+            tool_name=tool_name,
+            version=version,
+            ok=ok,
+            data=data,
+            error=error,
+            cache={"hit": False, "key": ck, "ttl_seconds": ttl},
+            latency_ms=latency_ms,
+            metadata={"server": tool.get("server"), **server_metadata},
+        )
+    except Exception as exc:
+        latency_ms = int((time.perf_counter() - started) * 1000)
+        audit("mcp.tool.failed", {"tool": tool_name, "latency_ms": latency_ms, "error": str(exc)})
+        return ToolResult(
+            tool_name=tool_name,
+            version=version,
+            ok=False,
+            error=str(exc),
+            latency_ms=latency_ms,
+            metadata={"server": tool.get("server")},
+        )

apps/mcp_gateway/requirements.txt

@@ -1,5 +1,5 @@
-fastapi>=0.111
+fastapi>=0.110
-uvicorn[standard]>=0.30
+uvicorn[standard]>=0.27
-pydantic>=2
+pydantic>=2.6
+PyYAML>=6.0
 httpx>=0.27
-PyYAML>=6

deploy/k8s/mcp-gateway.yaml

@@ -3,34 +3,34 @@ kind: Deployment
 metadata:
   name: mcp-gateway
   labels:
-    app.kubernetes.io/name: mcp-gateway
+    app: mcp-gateway
-    app.kubernetes.io/part-of: agent-framework-oci
 spec:
-  replicas: 1
+  replicas: 2
   selector:
     matchLabels:
-      app.kubernetes.io/name: mcp-gateway
+      app: mcp-gateway
   template:
     metadata:
       labels:
-        app.kubernetes.io/name: mcp-gateway
+        app: mcp-gateway
-        app.kubernetes.io/part-of: agent-framework-oci
     spec:
-      serviceAccountName: agent-framework-oci
+      serviceAccountName: mcp-gateway-sa
       containers:
         - name: mcp-gateway
-          image: mcp-gateway:latest
+          image: registry.example.com/agent-platform/mcp-gateway:1.0.0
-          imagePullPolicy: IfNotPresent
           ports:
-            - containerPort: 9200
+            - containerPort: 8300
+          env:
+            - name: MCP_GATEWAY_CONFIG_PATH
+              value: /app/config/mcp_gateway.yaml
           readinessProbe:
             httpGet:
-              path: /health
+              path: /ready
-              port: 9200
+              port: 8300
           livenessProbe:
             httpGet:
               path: /health
-              port: 9200
+              port: 8300
 ---
 apiVersion: v1
 kind: Service
@@ -38,8 +38,7 @@ metadata:
   name: mcp-gateway
 spec:
   selector:
-    app.kubernetes.io/name: mcp-gateway
+    app: mcp-gateway
   ports:
-    - name: http
+    - port: 8300
-      port: 9200
+      targetPort: 8300
-      targetPort: 9200

docs/MODULAR_REMAP.md

@@ -10,8 +10,8 @@ Esta entrega reorganiza o projeto para uma arquitetura corporativa modular, pres
 | `agent_gateway/` | `apps/agent_gateway/` |
 | `channel_gateway/` | `apps/channel_gateway/` |
 | `agent_frontend/` | `apps/agent_frontend/` |
-| `agent_template_backend/` | `templates/backend/` |
+| `agent_template_backend/` | `templates/agent_template_backend/` |
-| `agent_template_backend_day_zero/` | `templates/backend_day_zero/` |
+| `agent_template_backend_day_zero/` | `templates/agent_template_backend_day_zero/` |
 | `mcp_servers/` | `mcp/servers/` |
 | `agent_certification_tests/` | `evals/certification/` |
 | `agent_framework_oci_evaluator/evaluator/` | `evals/offline/evaluator/` |

libs/agent_framework/config/mcp_servers.yaml

@@ -1,30 +1,16 @@
-# MCP servers registry.
+# Logical MCP server registry used by the framework for tool ownership.
-# transport=http keeps the legacy framework mock contract:
+# With MCP_GATEWAY_ENABLED=true, the framework does NOT call these endpoints directly;
-#   GET  <endpoint>/tools/list
+# it calls MCP_GATEWAY_URL and the dedicated gateway routes to the final servers.
-#   POST <endpoint>/tools/call
+# Keep these logical names aligned with config/tools.yaml mcp_server values.
-# transport=fastmcp uses official MCP Streamable HTTP, typically endpoint http://host:port/mcp
-# transport=sse uses official MCP SSE, typically endpoint http://host:port/sse
 servers:
-  #  telecom:
-  #    enabled: true
-  #    transport: fastmcp
-  #    endpoint: http://localhost:8001/mcp
-  #    description: Telecom FastMCP server using official MCP protocol
-  #
-  #  retail:
-  #    enabled: true
-  #    transport: fastmcp
-  #    endpoint: http://localhost:8002/mcp
-  #    description: Retail FastMCP server using official MCP protocol
-
   telecom:
     enabled: true
     transport: http
     endpoint: http://localhost:8100/mcp
-    description: Telecom legacy HTTP mock MCP server
+    description: Logical Telecom MCP server. Direct endpoint is kept only for fallback when MCP_GATEWAY_ENABLED=false.
 
   retail:
     enabled: true
     transport: http
     endpoint: http://localhost:8200/mcp
-    description: Retail legacy HTTP mock MCP server
+    description: Logical Retail MCP server. Direct endpoint is kept only for fallback when MCP_GATEWAY_ENABLED=false.

libs/agent_framework/src/agent_framework/config/settings.py

@@ -170,6 +170,15 @@ class Settings(BaseSettings):
     IDENTITY_CONFIG_PATH: str = './config/identity.yaml'
     MCP_PARAMETER_MAPPING_PATH: str = './config/mcp_parameter_mapping.yaml'
     MCP_TOOL_TIMEOUT_SECONDS: int = 30
+    # When enabled, the framework routes tool calls to the dedicated MCP Gateway
+    # instead of calling individual MCP servers directly. The gateway then owns
+    # server selection, retry, cache and policy enforcement.
+    MCP_GATEWAY_ENABLED: bool = False
+    MCP_GATEWAY_URL: str = 'http://localhost:8300'
+    MCP_GATEWAY_TIMEOUT_SECONDS: int = 60
+    MCP_GATEWAY_TOKEN: str | None = None
+    MCP_GATEWAY_AGENT_ID: str = 'telecom_contas'
+    MCP_GATEWAY_TENANT_ID: str = 'default'
 
     DEFAULT_CHANNEL: str = 'web'
     # Agent Framework channel input mode.

libs/agent_framework/src/agent_framework/mcp/tool_router.py

@@ -8,6 +8,7 @@ from agent_framework.identity import MCPParameterMapper
 from .registry import MCPRegistry
 from .client import MCPHttpClient
 from .models import MCPToolResult
+from agent_framework.gateways import MCPGatewayClient
 
 logger = logging.getLogger("agent_framework.mcp.tool_router")
 
@@ -30,12 +31,26 @@ class MCPToolRouter:
             settings.TOOLS_CONFIG_PATH,
         )
         self.client = MCPHttpClient(timeout_seconds=settings.MCP_TOOL_TIMEOUT_SECONDS)
+        self.gateway_enabled = bool(getattr(settings, "MCP_GATEWAY_ENABLED", False))
+        self.gateway_agent_id = getattr(settings, "MCP_GATEWAY_AGENT_ID", "telecom_contas")
+        self.gateway_tenant_id = getattr(settings, "MCP_GATEWAY_TENANT_ID", "default")
+        self.gateway_client = (
+            MCPGatewayClient(
+                base_url=getattr(settings, "MCP_GATEWAY_URL", "http://localhost:8300"),
+                token=getattr(settings, "MCP_GATEWAY_TOKEN", None),
+                timeout_seconds=getattr(settings, "MCP_GATEWAY_TIMEOUT_SECONDS", settings.MCP_TOOL_TIMEOUT_SECONDS),
+            )
+            if self.gateway_enabled
+            else None
+        )
         self.parameter_mapper = MCPParameterMapper.from_yaml(
             getattr(settings, "MCP_PARAMETER_MAPPING_PATH", "./config/mcp_parameter_mapping.yaml")
         )
         logger.info(
-            "MCPToolRouter carregado enabled=%s servers=%s tools=%s mapper=%s",
+            "MCPToolRouter carregado enabled=%s gateway_enabled=%s gateway_url=%s servers=%s tools=%s mapper=%s",
             self.enabled,
+            self.gateway_enabled,
+            getattr(settings, "MCP_GATEWAY_URL", None),
             list(self.registry.servers.keys()),
             list(self.registry.tools.keys()),
             getattr(settings, "MCP_PARAMETER_MAPPING_PATH", None),
@@ -116,27 +131,55 @@ class MCPToolRouter:
             bool(mapped_arguments.get("invoice_id") or mapped_arguments.get("current_invoice_number")),
         )
 
+        async def _execute() -> MCPToolResult:
+            if self.gateway_enabled and self.gateway_client:
+                response = await self.gateway_client.invoke_tool(
+                    tenant_id=self.gateway_tenant_id,
+                    agent_id=self.gateway_agent_id,
+                    channel=getattr(self.settings, "DEFAULT_CHANNEL", "web"),
+                    tool_name=tool_name,
+                    arguments=mapped_arguments,
+                    business_context={},
+                    metadata={"routed_by": "agent_framework.mcp.tool_router", "logical_server": server.name},
+                )
+                return MCPToolResult(
+                    tool_name=tool_name,
+                    server_name="mcp_gateway",
+                    ok=bool(response.get("ok", False)),
+                    result=response.get("data"),
+                    error=response.get("error"),
+                    metadata={
+                        "transport": "mcp_gateway",
+                        "logical_server": server.name,
+                        **(response.get("metadata") or {}),
+                        "cache": response.get("cache") or {},
+                        "latency_ms": response.get("latency_ms"),
+                    },
+                )
+            return await self.client.call_tool(server, tool_name, mapped_arguments)
+
         if self.telemetry:
             async with self.telemetry.span(
                 "mcp.tool_call",
                 tool_name=tool_name,
-                mcp_server=server.name,
+                mcp_server=("mcp_gateway" if self.gateway_enabled else server.name),
                 input=mapped_arguments,
-                tags=["mcp", "tool"],
+                tags=["mcp", "tool", "mcp_gateway" if self.gateway_enabled else "mcp_server"],
             ):
-                result = await self.client.call_tool(server, tool_name, mapped_arguments)
+                result = await _execute()
                 await self.telemetry.event(
                     "mcp.tool_call.completed",
                     {
                         "tool_name": tool_name,
-                        "server": server.name,
+                        "server": "mcp_gateway" if self.gateway_enabled else server.name,
+                        "logical_server": server.name,
                         "ok": result.ok,
                         "error": result.error,
                     },
                 )
                 return result
 
-        return await self.client.call_tool(server, tool_name, mapped_arguments)
+        return await _execute()
 
     async def call(
         self,

pyproject.toml

@@ -7,5 +7,5 @@ requires-python = ">=3.10"
 [tool.agent_framework_oci.layout]
 libs = ["libs/agent_framework"]
 apps = ["apps/agent_gateway", "apps/channel_gateway", "apps/ai_gateway", "apps/mcp_gateway"]
-templates = ["templates/backend", "templates/backend_day_zero"]
+templates = ["templates/agent_template_backend", "templates/agent_template_backend_day_zero"]
 evals = ["evals/offline", "evals/certification"]

scripts/run_mcp_gateway.sh

@@ -1,4 +1,4 @@
 #!/usr/bin/env bash
 set -euo pipefail
 cd "$(dirname "$0")/../apps/mcp_gateway"
-uvicorn app.main:app --host 0.0.0.0 --port 9200 --reload
+uvicorn app.main:app --host 0.0.0.0 --port 8300 --reload

specs/SPEC-001-Architecture.md

@@ -17,7 +17,7 @@ A Agent Platform OCI é composta por componentes reutilizáveis, aplicações de
 | `mcp/servers` | Apps | MCP servers de domínio. |
 | `evals/offline` | App/Lib | Avaliação offline/batch. |
 | `evals/certification` | Suite | Certificação técnica e funcional. |
-| `templates/backend` | Template | Scaffold para novos agentes. |
+| `templates/agent_template_backend` | Template | Scaffold para novos agentes. |
 | `specs` | Documentação | Contratos SDD versionados. |
 | `deploy` | Operação | Docker, Kubernetes e Helm. |
 
@@ -40,8 +40,8 @@ agent_platform_oci/
 │   ├── offline/
 │   └── certification/
 ├── templates/
-│   ├── backend/
+│   ├── agent_template_backend/
-│   └── backend_day_zero/
+│   └── agent_template_backend_day_zero/
 ├── specs/
 ├── deploy/
 │   ├── docker/
@@ -76,7 +76,7 @@ flowchart LR
 | Agent Backend / Runtime | 8000 | Kubernetes Deployment | Horizontal com storage externo |
 | Channel Gateway | 7000 | Kubernetes Deployment | Horizontal |
 | AI Gateway | 9100 | Kubernetes Deployment | Horizontal |
-| MCP Gateway | 9200 | Kubernetes Deployment | Horizontal |
+| MCP Gateway | 8300 | Kubernetes Deployment | Horizontal |
 | MCP Servers | 8001+ | Kubernetes Deployment | Por domínio |
 | Evaluator API | 9300 | Deployment/CronJob | Por carga batch |
 | Frontend Demo | 5173 | Opcional | Não crítico |

specs/SPEC-008-Deployment.md

@@ -172,7 +172,7 @@ Itens considerados:
 ```bash
 curl -f http://agent-runtime:8000/health
 curl -f http://agent-gateway:9000/health
-curl -f http://mcp-gateway:9200/health
+curl -f http://mcp-gateway:8300/health
 curl -f http://ai-gateway:9100/health
 ```
 

specs/SPEC-010-Agent-Development.md

@@ -7,7 +7,7 @@ Esta SPEC define o padrão para criação de agentes usando templates, configura
 ## Estrutura do Template
 
 ```text
-templates/backend/
+templates/agent_template_backend/
 ├── app/
 │   ├── main.py
 │   ├── state.py

specs/SPEC-014-Templates-and-Agent-Creation-Model.md

@@ -49,7 +49,7 @@ Sem template:
 | Template | Uso |
 | --- | --- |
 | backend | Criação de agentes com runtime. |
-| backend_day_zero | Bootstrap acelerado com exemplos. |
+| agent_template_backend_day_zero | Bootstrap acelerado com exemplos. |
 | mcp_server | Criação de MCP server. |
 | channel_adapter | Adapter de canal quando aplicável. |
 
@@ -111,7 +111,7 @@ my_agent/
 ## Passo 1 — Copiar template
 
 ```bash
-cp -R templates/backend financeiro_agent
+cp -R templates/agent_template_backend financeiro_agent
 cd financeiro_agent
 ```
 

templates/agent_template_backend/.env

@@ -77,6 +77,7 @@ LANGFUSE_HOST=http://localhost:3005
 ENABLE_OTEL=false
 OTEL_EXPORTER_OTLP_ENDPOINT=
 OTEL_SERVICE_NAME=ai-agent-template
+ENABLE_LANGFUSE_OPENAI_AUTO_INSTRUMENTATION=true
 
 ###############################################################################
 # Analytics / Observer corporativo
@@ -165,3 +166,15 @@ MEMORY_MAX_SUMMARY_CHARS=6000
 MEMORY_SUMMARY_USE_LLM=true
 MEMORY_INJECT_RECENT_MESSAGES=true
 MEMORY_INJECT_SUMMARY=true
+
+###############################################################################
+# MCP Gateway
+###############################################################################
+# true = framework routes tool calls to the dedicated MCP Gateway.
+# false = framework calls MCP servers directly from mcp_servers.yaml.
+MCP_GATEWAY_ENABLED=true
+MCP_GATEWAY_URL=http://localhost:8300
+MCP_GATEWAY_TIMEOUT_SECONDS=60
+# MCP_GATEWAY_TOKEN=
+MCP_GATEWAY_AGENT_ID=telecom_contas
+MCP_GATEWAY_TENANT_ID=default

templates/agent_template_backend_day_zero/.env

@@ -77,6 +77,7 @@ LANGFUSE_HOST=http://localhost:3005
 ENABLE_OTEL=false
 OTEL_EXPORTER_OTLP_ENDPOINT=
 OTEL_SERVICE_NAME=ai-agent-template
+ENABLE_LANGFUSE_OPENAI_AUTO_INSTRUMENTATION=true
 
 ###############################################################################
 # Analytics / Observer corporativo
@@ -165,3 +166,15 @@ MEMORY_MAX_SUMMARY_CHARS=6000
 MEMORY_SUMMARY_USE_LLM=true
 MEMORY_INJECT_RECENT_MESSAGES=true
 MEMORY_INJECT_SUMMARY=true
+
+###############################################################################
+# MCP Gateway
+###############################################################################
+# true = framework routes tool calls to the dedicated MCP Gateway.
+# false = framework calls MCP servers directly from mcp_servers.yaml.
+MCP_GATEWAY_ENABLED=true
+MCP_GATEWAY_URL=http://localhost:8300
+MCP_GATEWAY_TIMEOUT_SECONDS=60
+# MCP_GATEWAY_TOKEN=
+MCP_GATEWAY_AGENT_ID=telecom_contas
+MCP_GATEWAY_TENANT_ID=default