リモート MCP サーバーの使用

Overview

このガイドでは、エージェントをリモート MCP（Model Context Protocol）サーバーに接続する方法を学習できます。 Atlas Agent Engine は、スタートアップ時に構成済みの MCP サーバーからツールを検出し、それらをエージェントコードで使用できるようにします。

MCPサーバーの構成は、 Pythonと TypeScript エージェントで同一です。エージェントコードのみが異なります。 Pythonエージェントは app.get_tools() メソッドを使用してツールにアクセスし、@app.tool() 修飾子は必要ありません。 TypeScript エージェントは app.getTools() メソッドを使用してツールにアクセスします。

Atlas Agent Engine は Streamable HTTP MCP トランスポートをサポートしており、リモート MCP サーバーで認証するための 2 つの方法を提供します。

• Bearer トークン（bearer_env 値）: プラットフォームは環境変数から静的トークンを読み取り、すべてのリクエストに対してAuthorization: Bearer ヘッダーとしてそれを添付します。

• OAuth2.1 （oauth 値）: プラットフォームは、 コマンドによって入力されたトークンキャッシュを使用し、アクセスagentengine dev mcp auth login トークンの有効期限が切れると自動的に更新されます。

同じファイルでいずれかの認証方法または両方の認証方法を使用できます。 mcp.servers セクションの各サーバーは独自の認証方法を個別に指定するため、同じ agent.yamlファイルで Bearer 認証サーバーと OAuth 認証サーバーに接続できます。

前提条件

始める前に、以下のものを必ず用意してください。

• agentengineCLI がインストールおよび認証されました。詳細については、 「インストールと認証のガイド」を参照してください。

• ファイルを持つ有効なエージェントプロジェクト。詳しくは、「 プロジェクトの作成agent.yaml 」ガイドを参照してください。

• リモート MCPサーバーの認証情報 : ベアラー トークン認証用のパーソナル アクセス トークン、または OAuth認証用の OAuth アクセス権を持つアカウント。

Bearer トークン認証の構成

MCPサーバーが静的パーソナル アクセス トークンを受け入れる場合は、ベアラ トークン認証を使用します。

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

OAuth 認証の構成

MCPサーバーがOAuth 2.1 をサポートしている場合は、OAuth認証を使用します。エージェントスタックを起動する前に、agentengine dev mcp auth login コマンドを実行してトークンキャッシュにデータを入力する必要があります。

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

エージェント コードの書込み

リモート MCP サーバーを使用するエージェントのカスタム ツールを定義する必要はありません。代わりに、次のメソッドを使用して、構成されたすべての MCP サーバーから検出されたツールにアクセスします。

• Python: app.get_tools() メソッドと app.get_tool_schemas() メソッド

• TypeScript: app.getTools() メソッドと app.getToolSchemas() メソッド

次の例は、リモート MCP ツールを使用する最小の配置可能なエージェントを示しています。エージェントはLgGraph StateGraph を使用して、LDM と MCP ツール間でメッセージをルーティングします。 LM は呼び出すツールを決定し、ToolNodeクラスがツール呼び出しを実行し、その結果は LM に渡され、ツール呼び出しが不要になるまで渡されます。

対応する例を表示するには、エージェントの言語のタブを選択します。

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

サーバーの命名ルール

サーバー名は mcp.servers セクションの下のキーです。名前には、非 ASCII 文字やドット付き名前を含む、印刷可能な UTF-8 でエンコードされたテキストを最大 128 文字含めることができます。名前は空にすることも、次の要素を含めることはできません。

• 空白のみのテキスト

• 先頭または末尾の空白

• 制御、ゼロ幅、バイト順マーク（BOM）、または双方向文字

• パス区切り文字（/ または \）

• ..

agentengine agent validateコマンドは、これらのルールに対して名前を検証します。詳細については、「 構成の検証 」を参照してください。

MCP サーバー構成スキーマ

次の表は、agent.yamlファイルの mcp.servers セクションで使用できるフィールドを説明したものです。

複数の MCP サーバーへの接続

単一の agent.yamlファイル内の mcp.servers セクション内で複数のサーバーを定義できます。 Atlas Agent Engine は、スタートアップ時にすべての設定されたサーバーに接続し、そのツールをエージェントのツール画面にマージします。次の例では、GitHub、セカンダリ、Grant サーバーを単一の 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

OAuth認証を使用して複数のサーバーに接続する場合は、環境を起動する前に、各agentengine dev mcp auth login <name> OAuthサーバーに対して コマンドを実行する必要があります。次の例は、環境を起動する前にセカンダリ サーバーと Glas サーバーの両方で認証するためにエージェントのプロジェクトディレクトリから実行するコマンドを示しています。

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

配置用の MCP 認証情報をプロビジョニング

.envファイルとローカル OAuth トークンキャッシュは、agentengine dev up コマンドを使用したローカル開発中にのみ使用できます。エージェントを配置する前に、配置されたランタイムが各 MCPサーバーで認証できるように、MCP 認証情報をワークスペース シークレットとしてプロビジョニングする必要があります。

以下のセクションでは、各認証タイプのシークレットをプロビジョニングする方法について説明します。シークレットのプロビジョニングの詳細については、「 クラウド シークレットのプロビジョニング 」ガイドを参照してください。

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

次のステップ

エージェントがリモート MCP サーバーに接続されたら、ローカルでテストしてから配置できます。エージェントをローカルでテストして配置する方法の詳細については、Atlas Agent Engine ドキュメントの次のガイドを参照してください。

• エージェントをテストする

• エージェントの配置