# SPEC-004 — MCP Gateway

## Scope

O MCP Gateway centraliza Catalog, Authorization, Routing, Execution, cache, timeout, retry, Observability and Response padronizada of tools MCP.

## Endpoints

| Method | Endpoint | Description |
|---|---|---|
| `GET` | `/health` | Health check. |
| `GET` | `/ready` | Readiness check. |
| `GET` | `/v1/tools` | Catalog of tools. |
| `GET` | `/v1/tools/{tool_name}` | Detalhe of the tool. |
| `POST` | `/v1/tools/{tool_name}/invoke` | Execution of tool. |
| `GET` | `/v1/servers` | Lista MCP servers. |

## ToolInvocation

```json
{
  "tenant_id": "default",
  "agent_id": "telecom_contas",
  "tool_name": "consultar_fatura",
  "arguments": {
    "msisdn": "11999999999",
    "invoice_id": "3000131180",
    "session_id": "default:telecom_contas:session-001"
  },
  "business_context": {
    "customer_key": "11999999999",
    "contract_key": "3000131180",
    "session_key": "session-001"
  },
  "metadata": {
    "request_id": "req-001",
    "trace_id": "trace-001"
  }
}
```

## ToolResult

```json
{
  "tool_name": "consultar_fatura",
  "ok": true,
  "data": {
    "invoice_id": "3000131180",
    "valor_total": 249.90,
    "vencimento": "2026-06-10",
    "status": "ABERTA"
  },
  "cache": {
    "hit": false,
    "ttl_seconds": 300
  },
  "latency_ms": 140,
  "metadata": {
    "server": "telecom"
  }
}
```

## mcp_servers.yaml

```yaml
servers:
  telecom:
    transport: http
    url: http://telecom-mcp:8001/mcp
    enabled: true
    timeout_seconds: 30

  retail:
    transport: http
    url: http://retail-mcp:8002/mcp
    enabled: true
    timeout_seconds: 30
```

## tools.yaml

```yaml
tools:
  consultar_fatura:
    server: telecom
    enabled: true
    idempotent: true
    cache_ttl_seconds: 300
    allowed_agents:
      - telecom_contas
    required_business_keys:
      - customer_key
      - contract_key

  solicitar_devolucao:
    server: retail
    enabled: true
    idempotent: false
    requires_confirmation: true
    allowed_agents:
      - retail_orders
```

## mcp_parameter_mapping.yaml

```yaml
tools:
  consultar_fatura:
    map:
      customer_key: msisdn
      contract_key: invoice_id
      interaction_key: ura_call_id
      session_key: session_id
```

## Authorization

```yaml
authorization:
  default_policy: deny
  agents:
    telecom_contas:
      allowed_tools:
        - consultar_fatura
        - consultar_pagamentos
        - consultar_plano
```

## Cache

| Regra | value |
|---|---|
| Chave | `tenant_id:agent_id:tool_name:hash(arguments)` |
| Aplicação | only tools idempotentes |
| Bypass | `metadata.cache_bypass=true` |
| TTL | `cache_ttl_seconds` |
| Escrita | No cachear operações mutáveis |

## Retry and Timeout

```yaml
execution:
  default_timeout_seconds: 30
  retry:
    enabled: true
    max_attempts: 2
    backoff_ms: 250
  circuit_breaker:
    enabled: true
    failure_threshold: 5
    recovery_seconds: 60
```

## Events

| Evento | Description |
|---|---|
| `mcp.tool.requested` | Tool requisitada. |
| `mcp.tool.authorized` | Authorization aprovada. |
| `mcp.tool.denied` | Authorization negada. |
| `mcp.tool.started` | Execution iniciada. |
| `mcp.tool.completed` | Execution concluída. |
| `mcp.tool.failed` | Execution failed. |
| `mcp.cache.hit` | Cache hit. |
| `mcp.cache.miss` | Cache miss. |

## Metrics

| metric | Dimensões |
|---|---|
| `mcp_tool_calls_total` | tool, server, tenant, agent, status |
| `mcp_tool_latency_ms` | tool, server |
| `mcp_tool_errors_total` | tool, server, error_type |
| `mcp_cache_hits_total` | tool |
| `mcp_cache_misses_total` | tool |

## Security

- Tools are negadas por Standard.
- Argumentos sensíveis are mascarados.
- Tools mutáveis exigem confirmação when configured.
- MCP servers No recebem payload bruto of canal.
- Credenciais of backend are mantidas nos MCP servers or secret store.


## Requirements No Funcionais

| Categoria | Requirement |
|---|---|
| Availability | Components deployáveis expõem `/health` and `/ready`. |
| Escalabilidade | Apps stateless escalam horizontalmente. State conversational fica em repositórios external. |
| Security | Segredos are fornecidos por secret store or Kubernetes Secrets. |
| Observability | Logs, Metrics and traces usam correlation por request_id, trace_id, session_id, tenant_id and agent_id. |
| Auditabilidade | Decisions of rota, guardrail, judge, MCP and LLM are rastreáveis. |
| Portabilidade | Execution suportada em local, Docker Compose and Kubernetes/OKE. |
| Configuration | Comportamento variável is controlado por `.env` and YAML versionado. |


## Acceptance criteria

- [ ] Catalog of tools retorna tools habilitadas.
- [ ] ToolInvocation is validado before of the Execution.
- [ ] Authorization por Agent is aplicada.
- [ ] Parâmetros are derivados of the BusinessContext.
- [ ] Cache só is applied a tools idempotentes.
- [ ] Timeout/retry/circuit breaker are configuráveis.
- [ ] Events and Metrics are emitidos.
- [ ] Failures retornam ToolResult padronizado.
- [ ] MCP servers are substituíveis por Configuration.
- [ ] Tools críticas possuem Tests of Contract.


## Glossário

| Termo | Definição |
|---|---|
| Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contracts and Components operational. |
| Agent Framework | Biblioteca/core reutilizável with contracts, guardrails, judges, Memory, telemetria, providers and utilitários. |
| Agent Runtime | Motor of Execution of Agents based on LangGraph, State, Session, Memory, checkpoints, Routing and ciclo of vida. |
| Agent Gateway | Aplicação deployável of Input, Routing and orquestração between backends/Agents. |
| Channel Gateway | Aplicação or módulo of normalização of payloads of canais for GatewayRequest. |
| AI Gateway | Aplicação of Governance, Routing and abstração of Calls LLM/embedding. |
| MCP Gateway | Aplicação of Governance and Routing of tools MCP. |
| Evaluator | layer of Evaluation online/offline, regressão and Certification. |
| Business Context | Conjunto of chaves canônicas of negócio: customer_key, contract_key, interaction_key, account_key, resource_key and session_key. |

## Policy mínima of Operations

before forward a tool, The runtime must apply a Policy Optional of the backend em `config/tool_policies.yaml`. Os tipos canônicos are `read_only` and `transactional`; esta última can exigir confirmação booleana explícita and fields required. A ausência of the file No is Error and preserva os fields legados of `tools.yaml`. A Policy conversational No substitui Authentication, Authorization, idempotência nem atomicidade no MCP Server.