Utilice servidores MCP remotos

Overview

En esta guía, aprenderá a conectar su agente a servidores remotos del Protocolo de Contexto de Modelo (MCP). El motor de agentes de Atlas detecta las herramientas de los servidores MCP configurados al iniciarse y las pone a disposición del código de su agente.

La configuración del servidor MCP es idéntica para los agentes de Python y TypeScript. Solo difiere el código del agente. Los agentes de Python acceden a las herramientas mediante el método app.get_tools() y no requieren decoradores @app.tool(). Los agentes de TypeScript acceden a las herramientas mediante el método app.getTools().

El motor de agente Atlas admite el transporte MCP HTTP Streamable y proporciona dos métodos para autenticarse con servidores MCP remotos:

• Token de portador (valor bearer_env): La plataforma lee un token estático de una variable de entorno y lo adjunta como un encabezado Authorization: Bearer en cada solicitud.

• OAuth 2.1 (valor oauth): La plataforma utiliza una caché de tokens rellenada por el comando agentengine dev mcp auth login y actualiza automáticamente los tokens de acceso cuando caducan.

Puedes usar uno o ambos métodos de autenticación en el mismo archivo. Cada servidor en la sección mcp.servers especifica su propio método de autenticación de forma independiente, por lo que puedes conectarte a un servidor autenticado mediante bearer y a un servidor autenticado mediante OAuth en el mismo archivo agent.yaml.

Requisitos previos

Antes de comenzar, asegúrate de tener lo siguiente:

• La interfaz de línea de comandos agentengine se instaló y autenticó correctamente. Para obtener más información, consulte la guía de instalación y autenticación.

• Un proyecto de agente válido con un archivo agent.yaml. Para obtener más información, consulte la guía Crear un proyecto.

• Credenciales para su servidor MCP remoto: un token de acceso personal para la autenticación mediante token de portador, o una cuenta con acceso OAuth para la autenticación OAuth.

Configurar la autenticación mediante token de portador

Utilice la autenticación mediante token de portador cuando el servidor MCP acepte un token de acceso personal estático.

GITHUB_MCP_TOKEN=<your-personal-access-token>

mcp:
  servers:
    github:
      transport: streamable_http
      url: https://api.githubcopilot.com/mcp/
      headers:
        X-MCP-Readonly: "true"
        X-MCP-Toolsets: repos,issues,pull_requests,actions
      auth:
        type: bearer_env
        token_env: GITHUB_MCP_TOKEN
      timeout_seconds: 30

agentengine dev up

Configurar la autenticación OAuth

Utilice la autenticación OAuth cuando el servidor MCP admita OAuth 2.1. Debe ejecutar el comando agentengine dev mcp auth login para llenar la caché de tokens antes de iniciar la pila de agentes.

mcp:
  servers:
    sentry:
      transport: streamable_http
      url: https://mcp.sentry.dev/mcp
      auth:
        type: oauth
        scope: "org:read project:read team:read event:read"
      timeout_seconds: 30

agentengine dev mcp auth login sentry

agentengine dev up

Escribir código de agente

No es necesario definir herramientas personalizadas para los agentes que utilizan servidores MCP remotos. En su lugar, utilice los siguientes métodos para acceder a las herramientas detectadas desde todos los servidores MCP configurados:

• Python: métodos app.get_tools() y app.get_tool_schemas()

• TypeScript: métodos app.getTools() y app.getToolSchemas()

Los siguientes ejemplos muestran un agente mínimo desplegable que utiliza herramientas MCP remotas. El agente utiliza un LangGraph StateGraph para enrutar mensajes entre el LLM y las herramientas MCP. El LLM decide qué herramienta llamar, la clase ToolNode ejecuta la llamada a la herramienta y el resultado se devuelve al LLM hasta que no se necesiten más llamadas a herramientas.

Seleccione la pestaña correspondiente al idioma de su agente para ver el ejemplo correspondiente:

from typing import Annotated, TypedDict
from langchain_core.messages import BaseMessage
from langchain_openai import ChatOpenAI
from langgraph.graph import END, START, StateGraph
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode
from agent_engine_sdk_langgraph import App
app = App(app_name="my-mcp-agent")
class AgentState(TypedDict):
    messages: Annotated[list[BaseMessage], add_messages]
@app.entrypoint
def build_agent():
    llm = app.llm(ChatOpenAI(model="gpt-4o-mini"))
    tools = app.get_tools()
    llm_with_tools = llm.bind_tools(app.get_tool_schemas())
    def call_model(state: AgentState):
        return {"messages": [llm_with_tools.invoke(state["messages"])]}
    def should_continue(state: AgentState):
        last = state["messages"][-1]
        return "tools" if getattr(last, "tool_calls", None) else "end"
    graph = StateGraph(AgentState)
    graph.add_node("agent", call_model)
    graph.add_node("tools", ToolNode(tools))
    graph.add_edge(START, "agent")
    graph.add_conditional_edges(
        "agent", should_continue, {"tools": "tools", "end": END}
    )
    graph.add_edge("tools", "agent")
    return graph.compile(checkpointer=app.checkpointer())
app.run()

import "dotenv/config";
import { BaseMessage } from "@langchain/core/messages";
import { Annotation, END, START, StateGraph } from "@langchain/langgraph";
import { ToolNode } from "@langchain/langgraph/prebuilt";
import { ChatOpenAI } from "@langchain/openai";
import { App } from "@mongodb-js/agent-engine-sdk-langgraph";
export const app = new App({ appName: "my-mcp-agent" });
const AgentStateAnnotation = Annotation.Root({
  messages: Annotation<BaseMessage[]>({
    reducer: (left, right) => left.concat(right),
    default: () => [],
  }),
});
type AgentState = typeof AgentStateAnnotation.State;
export const buildAgent = app.entrypoint(() => {
  const llm = app.llm(new ChatOpenAI({ model: "gpt-4o-mini" }));
  const tools = [...app.getTools()];
  const llmWithTools = llm.bindTools([...app.getToolSchemas()]);
  const callModel = async (state: AgentState) => {
    const response = await llmWithTools.invoke(state.messages);
    return { messages: [response] };
  };
  const shouldContinue = (state: AgentState) => {
    const last = state.messages[state.messages.length - 1];
    const toolCalls = (last as { tool_calls?: unknown[] }).tool_calls;
    return Array.isArray(toolCalls) && toolCalls.length > 0
      ? "tools"
      : END;
  };
  return new StateGraph(AgentStateAnnotation)
    .addNode("agent", callModel)
    .addNode("tools", new ToolNode(tools))
    .addEdge(START, "agent")
    .addConditionalEdges("agent", shouldContinue, {
      tools: "tools",
      [END]: END,
    })
    .addEdge("tools", "agent")
    .compile({ checkpointer: app.checkpointer() });
});
app.run();

Reglas para nombrar servidores

El nombre del servidor es una clave en la sección mcp.servers. Un nombre puede contener hasta 128 caracteres de texto imprimible codificado en UTF-8, incluidos caracteres no ASCII y nombres con puntos. Un nombre no puede estar vacío ni contener los siguientes elementos:

• Texto solo con espacios en blanco

• Espacio en blanco inicial o final

• Caracteres de control, de ancho cero, de marca de orden de bytes (BOM) o bidireccionales

• Separadores de ruta (/ o \)

• ..

El comando agentengine agent validate valida los nombres según estas reglas. Para obtener más información, consulte Validar configuración.

Esquema de configuración del servidor MCP

La siguiente tabla describe los campos disponibles en la sección mcp.servers de su archivo agent.yaml:

Conectar varios servidores MCP

Puedes definir varios servidores dentro de la sección mcp.servers en un único archivo agent.yaml. El motor del agente Atlas se conecta a todos los servidores configurados al iniciarse e integra sus herramientas en la interfaz del agente. El siguiente ejemplo conecta simultáneamente los servidores GitHub, Sentry y Glean en un único archivo agent.yaml:

mcp:
  servers:
    github:
      transport: streamable_http
      url: https://api.githubcopilot.com/mcp/
      headers:
        X-MCP-Readonly: "true"
        X-MCP-Toolsets: repos,issues,pull_requests,actions
      auth:
        type: bearer_env
        token_env: GITHUB_MCP_TOKEN
      timeout_seconds: 30
    sentry:
      transport: streamable_http
      url: https://mcp.sentry.dev/mcp
      auth:
        type: oauth
        scope: "org:read project:read team:read event:read"
      timeout_seconds: 30
    glean:
      transport: streamable_http
      url: https://mongodb-be.glean.com/mcp/default
      auth:
        type: oauth
        scope: "SEARCH DOCUMENTS ENTITIES"
        client_name: My Glean MCP Agent
      timeout_seconds: 30

Cuando te conectas a varios servidores con autenticación OAuth, debes ejecutar el comando agentengine dev mcp auth login <name> para cada servidor OAuth antes de iniciar el entorno. El siguiente ejemplo muestra los comandos que debes ejecutar desde el directorio de tu proyecto de agente para autenticarte con los servidores Sentry y Glean antes de iniciar el entorno:

agentengine dev mcp auth login sentry
agentengine dev mcp auth login glean
agentengine dev up

Proporcionar credenciales MCP para la implementación

El archivo .env y la caché local de tokens OAuth solo están disponibles durante el desarrollo local con el comando agentengine dev up. Antes de implementar el agente, debe aprovisionar las credenciales de MCP como secretos del espacio de trabajo para que el entorno de ejecución implementado pueda autenticarse con cada servidor MCP.

Las siguientes secciones describen cómo aprovisionar secretos para cada tipo de autenticación. Para obtener más información sobre el aprovisionamiento de secretos, consulte la guía «Aprovisionamiento de secretos en la nube».

agentengine secret set GITHUB_MCP_TOKEN --workspace-scope

agentengine secret set GITHUB_MCP_TOKEN --workspace-scope --sync

agentengine dev mcp auth upload sentry

agentengine dev mcp auth upload sentry --sync

Próximos pasos

Una vez que su agente esté conectado a los servidores MCP remotos, puede probarlo localmente y luego implementarlo. Para obtener más información sobre cómo probar su agente localmente e implementarlo, consulte las siguientes guías en la documentación de Atlas Agent Engine:

• Pon a prueba a tu agente.

• Implementar el Agente