Configurando Rastros de Ferramentas em Seu Gateway MCP

Um Agente faz uma chamada para um LLM. O LLM decide qual ferramenta do servidor MCP deve ser usada para uma tarefa. O Agente então faz uma chamada para essa ferramenta. Isso pode acontecer uma vez ou pode acontecer centenas de vezes.

Aqui está a pergunta: Você sabe quais ferramentas do servidor MCP foram usadas, quando foram usadas e de onde o prompt se originou? Em outras palavras, como você pode realmente rastrear e confirmar os rastros das ferramentas dentro do seu Gateway MCP?

É aí que ter um Gateway MCP que expõe esses rastros e métricas entra em cena.

Neste blog, você aprenderá como fazer a observabilidade completa de rastreamento de ponta a ponta para qualquer servidor e ferramenta MCP.

Pré-requisitos

Para acompanhar este post do blog de forma prática, você precisará de:

1. Um cluster k8s (local está bom).
2. Agentgateway OSS instalado, que você pode encontrar aqui.
3. Uma conta do GitHub porque você precisará de um PAT (token de acesso pessoal) para usar o servidor MCP do GitHub Copilot.

Se você não tiver um cluster k8s, há uma grande parte deste post que é bastante visual, então você pode acompanhar de um ponto de vista teórico.

Como o Agentgateway Exponha os Rastros MCP

O Agentgateway expõe a métrica agentgateway_mcp_requests_total que inclui:

• O método usado
• Recurso
• Servidor MCP
• ID da sessão MCP
• Nome da ferramenta
• Listener
• Rota
• Regras de roteamento

Eu posso visualizar as métricas dentro do agentgateway depois de fazer uma chamada para a ferramenta do servidor MCP, fazendo o port-forwarding do Pod do Gateway e usando um curl na porta 15020, que é o listener interno de métricas/estatísticas do pod agentgateway.

kubectl port-forward -n agentgateway-system pod/mcp-gateway-7f9f6679cd-d5jmg 15020:15020

curl -s http://127.0.0.1:15020/metrics | grep agentgateway_mcp_requests

E então eu posso ver a seguinte saída de métrica:

agentgateway_mcp_requests_total{method="tools/call",resource_type="tool",server="github-copilot",resource="get_me",bind="3000/agentgateway-system/mcp-gateway",gateway="agentgateway-system/mcp-gateway",listener="mcp",route="agentgateway-system/mcp-route",route_rule="unknown"} 1

No entanto, se você quiser coletar informações mais distintas dentro de uma ferramenta de rastreamento usando um coletor OTel, você pode usar expressões CEL para especificar o que deseja exportar:

  - name: mcp.tool_name
    expression: 'default(mcp.tool.name, "")'
  - name: mcp.tool_target
    expression: 'default(mcp.tool.target, "")'
  - name: mcp.method_name
    expression: 'default(mcp.methodName, "")'

O Agentgateway emite rastros básicos, mas com o acima, você pode enriquecer a saída do rastreamento com detalhes específicos do MCP.

Na próxima seção, você configurará uma configuração do agentgateway com o MCP para que os rastros possam ser visualizados dentro de uma ferramenta de observabilidade.

Configuração do Gateway e MCP

Com um pouco de teoria sobre o "como" e o "porquê" feita, vamos colocar a mão na massa e ver como configurar seu gateway e servidor MCP.

1. Crie um novo Gateway usando a Classe Gateway do agentgateway.

kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: mcp-gateway
  namespace: agentgateway-system
  labels:
    app: github-mcp-server
spec:
  gatewayClassName: agentgateway
  listeners:
    - name: mcp
      port: 3000
      protocol: HTTP
      allowedRoutes:
        namespaces:
          from: Same
EOF

1. Crie um segredo para autenticar com o servidor MCP do GitHub Copilot.

export GITHUB_PAT=

kubectl apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: github-pat
  namespace: agentgateway-system
type: Opaque
stringData:
  Authorization: "Bearer ${GITHUB_PAT}"
EOF

1. Crie um agentgatewaybackend, que informa ao Gateway para rotear para o servidor MCP do GitHub Copilot.

kubectl apply -f - <<EOF
apiVersion: agentgateway.dev/v1alpha1
kind: AgentgatewayBackend
metadata:
  name: github-mcp-server
  namespace: agentgateway-system
spec:
  mcp:
    targets:
      - name: github-copilot
        static:
          host: api.githubcopilot.com
          port: 443
          path: /mcp/
          protocol: StreamableHTTP
          policies:
            tls: {}
            auth:
              secretRef:
                name: github-pat
EOF

1. Crie um HTTPRoute com o agentgatewaybackend como referência/alvo.

kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: mcp-route
  namespace: agentgateway-system
  labels:
    app: github-mcp-server
spec:
  parentRefs:
    - name: mcp-gateway
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /mcp
      backendRefs:
        - name: github-mcp-server
          namespace: agentgateway-system
          group: agentgateway.dev
          kind: AgentgatewayBackend
EOF

Com o Gateway configurado, vamos fazer um teste para garantir que o servidor MCP pode ser conectado.

Teste Rápido

1. Recupere o endereço IP do ALB do seu gateway. Se você estiver executando um cluster k8s localmente, pode não ter isso, então você pode usar localhost sempre que $GATEWAY_IP for usado.

export GATEWAY_IP=$(kubectl get svc mcp-gateway -n agentgateway-system -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
echo $GATEWAY_IP

1. Abra o MCP Inspector, que é um cliente MCP popular.

npx modelcontextprotocol/inspector#0.18.0

Você deve ser capaz de ver a lista de ferramentas dentro do servidor MCP do GitHub Copilot.

Agora que sabemos que o servidor MCP funciona como esperado, vamos configurar a configuração de observabilidade.

Configuração de Observabilidade

Com o Gateway e o servidor MCP configurados e a conexão testada, é hora de configurar o mecanismo de rastreamento junto com o coletor OTel e a capacidade de visualizar os rastros de forma visual. Esta seção abordará como configurar o tempo, um coletor de rastreamento OTel, e kube-prometheus.

1. Instale o Tempo.

helm upgrade --install tempo tempo \
  --repo https://grafana.github.io/helm-charts \
  --version 1.16.0 \
  --namespace telemetry \
  --create-namespace \
  --values - <<EOF
persistence:
  enabled: false
tempo:
  receivers:
    otlp: