agent_platform_oci/specs/en/SPEC-004-MCP-Gateway.md

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

{
  "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

{
  "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

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

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

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

Authorization

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

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.