Usar servidores MCP remotos

Visão geral

Neste guia, você pode aprender como conectar seu agente a servidores remotos do Model Context Protocol (MCP). O Atlas Agent Engine descobre ferramentas de servidores MCP configurados na inicialização e as disponibiliza para o código do agente .

A configuração do servidor MCP é idêntica para agentes Python e TypeScript. Apenas o código do agente é diferente. Os agentes Python acessam ferramentas usando o método app.get_tools() e não exigem nenhum executor @app.tool(). Os agentes do TypeScript acessam as ferramentas usando o método app.getTools().

O Atlas Agent Engine suporta o transporte Streamable HTTP MCP e fornece dois métodos para autenticar com servidores MCP remotos:

• Token do portador (valor bearer_env): a plataforma lê um token estático de uma variável de ambiente e o anexa como um cabeçalho Authorization: Bearer em cada solicitação.

• OAuth 2.1 (valor oauth): a plataforma usa um cache de token preenchido pelo comando agentengine dev mcp auth login e atualiza os tokens de acesso automaticamente quando eles expiram.

Você pode usar um ou ambos os métodos de autenticação no mesmo arquivo. Cada servidor na seção mcp.servers especifica seu próprio método de autenticação de forma independente, para que você possa se conectar a um servidor autenticado por portador e a um servidor autenticado por OAuth no mesmo arquivo agent.yaml.

Pré-requisitos

Antes de começar, certifique-se de ter o seguinte:

• A CLI agentengine instalada e autenticada. Para saber mais, consulte o guia Instalar e autenticar.

• Um projeto de agente válido com um arquivo agent.yaml. Para saber mais, consulte o guia Criar um projeto.

• Credenciais para seu servidor MCP remoto : um token de acesso pessoal para autenticação de token de portador ou uma conta com acesso OAuth para autenticação OAuth.

Configurar autenticação de token de portador

Use a autenticação de token de portador quando o servidor MCP aceitar um token de acesso pessoal 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 autenticação OAuth

Use a autenticação OAuth quando o servidor MCP permitir OAuth 2.1. Você deve executar o comando agentengine dev mcp auth login para preencher o cache de token antes de iniciar a pilha de agente .

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

Gravar código do agente

Você não precisa definir ferramentas personalizadas para os agentes que usam servidores MCP remotos. Em vez disso, use os seguintes métodos para acessar as ferramentas detectadas em todos os servidores MCP configurados:

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

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

Os exemplos a seguir mostram um agente implementável mínimo que usa ferramentas MCP remotas. O agente usa um LangGraph StateGraph para rotear mensagens entre as ferramentas LLM e MCP. O LLM decide qual ferramenta chamar, a classe ToolNode executa a chamada de ferramenta e o resultado é passado de volta para o LLM até que nenhuma outra chamada de ferramenta seja necessária.

Selecione a guia do idioma do seu agente para ver o exemplo correspondente:

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();

Regras de nomenclatura do servidor

O nome de um servidor é uma chave na seção mcp.servers. Um nome pode conter até 128 caracteres de texto codificado em UTF8 imprimível, incluindo caracteres não ASCII e nomes pontilhados. Um nome não pode estar vazio ou conter os seguintes elementos:

• Texto somente para espaços em branco

• Espaço em branco à esquerda ou à direita

• Controle, largura zero, marca de ordem de bytes (BOM) ou caracteres bidirecionais

• Separadores de caminho (/ ou \)

• ..

O comando agentengine agent validate valida nomes em relação a estas regras. Para saber mais, consulte Validar Configuração.

Esquema de configuração do servidor MCP

A tabela a seguir descreve os campos disponíveis na seção mcp.servers do seu arquivo agent.yaml:

Conectar vários servidores do MCP

Você pode definir vários servidores dentro da seção mcp.servers em um único arquivo agent.yaml. O Atlas Agent Engine se conecta a todos os servidores configurados na inicialização e mescla suas ferramentas na superfície de ferramentas do agente. O exemplo a seguir conecta os servidores GitHub, Sentry e Glean simultaneamente em um único arquivo 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

Ao conectar a vários servidores com autenticação OAuth, você deve executar o comando agentengine dev mcp auth login <name> para cada servidor OAuth antes de iniciar o ambiente. O exemplo a seguir mostra os comandos a serem executados a partir do diretório de projeto do agente para autenticação nos servidores Sentry e Glean antes de iniciar o ambiente:

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

Provisionar Credenciais MCP para Implantação

O arquivo .env e o cache de token OAuth local estão disponíveis somente durante o desenvolvimento local com o comando agentengine dev up. Antes de implementar o agente, você deve provisionar as credenciais do MCP como segredos de espaço de trabalho para que o tempo de execução implantado possa se autenticar em cada servidor do MCP.

As seções a seguir descrevem como provisionar segredos para cada tipo de autenticação. Para saber mais sobre segredos de provisionamento, consulte o guia Segredos de Provision Cloud.

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 passos

Depois que seu agente estiver conectado aos servidores MCP remotos, você poderá testá-lo localmente e, em seguida, implementá-lo. Para saber mais sobre como testar seu agente localmente e implementá-lo, consulte os seguintes guias na documentação do Mecanismo do Agente do Atlas :

• Teste seu agente

• Implantar o Agente