개요
이 가이드 에서는 에이전트 를 원격 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 서버로 인증하는 두 가지 방법을 제공합니다.
베어러 토큰(
bearer_env값): 플랫폼은 환경 변수에서 정적 토큰을 읽고 모든 요청 에서 이를Authorization: Bearer헤더로 첨부합니다.OAuth 2.1 (
oauth값): 플랫폼은agentengine dev mcp auth login명령으로 채워진 토큰 캐시 사용하고 액세스 토큰이 만료되면 자동으로 새로 고칩니다.
동일한 파일 에서 인증 방법 중 하나 또는 둘 다를 사용할 수 있습니다. mcp.servers 섹션의 각 서버 자체 인증 방법을 독립적으로 지정하므로 동일한 agent.yaml 파일 에서 베어러 인증 서버 와 OAuth 인증 서버 에 연결할 수 있습니다.
전제 조건
시작하기 전에 다음 항목이 준비되어 있는지 확인하세요.
agentengineCLI 설치되고 인증되었습니다. 자세한 학습 은 설치 및 인증 가이드 참조하세요.agent.yaml파일 있는 유효한 에이전트 프로젝트 . 자세히 학습 프로젝트 만들기 가이드 참조하세요.원격 MCP 서버 의 자격 증명: 베어러 토큰 인증 위한 개인 액세스 토큰 또는 OAuth 인증 위한 OAuth 액세스 이 있는 계정.
베어러 토큰 인증 구성
MCP 서버 정적 개인 액세스 토큰을 허용하는 경우 베어러 토큰 인증 사용합니다.
agent.yaml 파일 에서 MCP 서버 구성합니다.
agent.yaml 파일 에 mcp.servers 섹션을 추가합니다. auth.type 필드 bearer_env 값으로 설정하고 auth.token_env 필드 토큰을 보유하는 환경 변수의 이름으로 설정합니다. 다음 예시 agent.yaml 파일 에서 GitHub MCP 서버 구성하는 방법을 보여줍니다.
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
OAuth 인증 구성
MCP 서버 OAuth 2를 지원할 때 OAuth 인증 사용합니다.1. 에이전트 스택 시작하기 전에 agentengine dev mcp auth login 명령을 실행 토큰 캐시 채워야 합니다.
agent.yaml 파일 에서 MCP 서버 구성합니다.
agent.yaml 파일 에 mcp.servers 섹션을 추가합니다. auth.type 필드 oauth 값으로 설정하고 필요한 OAuth 범위를 제공합니다. 다음 예시 agent.yaml 파일 에서 MCP 서버 구성하는 방법을 보여줍니다.
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
MCP 서버 로 인증합니다.
에이전트 프로젝트 디렉토리 에서 agent.yaml 파일 에 정의한 서버 이름을 사용하여 agentengine dev mcp auth login 명령을 실행 . 이 명령은 브라우저에서 OAuth 동의 흐름을 열고 토큰 캐시 ~/.agentengine/mcp-oauth 디렉토리 에 씁니다.
agentengine dev mcp auth login sentry
토큰 캐시 각 프로젝트 와 각 MCP 엔드포인트에 대해 별도입니다. 한 프로젝트 에서 로그인해도 다른 프로젝트 에 로그 되지 않으므로 프로젝트 당 한 번씩 agentengine dev mcp auth login 명령을 실행 해야 합니다.
로그인하는 동안 CLI 서버의 OAuth 권한 부여 엔드포인트를 검색합니다. 이 엔드포인트는 https 체계를 사용해야 합니다. 서버 다른 체계를 사용하는 권한 부여 엔드포인트를 알리면 agentengine dev mcp auth login 명령이 중지되고 Refused to open unauthorized MCP OAuth URL 오류가 생성됩니다.
참고
agentengine dev up 명령을 실행 전에 agentengine dev mcp auth login 명령을 실행 해야 합니다. 런타임은 스타트업 시 토큰 캐시 마운트하며 환경이 실행 후에는 인증할 수 없습니다.
에이전트 코드 작성
원격 MCP 서버를 사용하는 에이전트를 위한 사용자 지정 도구를 정의할 필요가 없습니다. 대신 다음 방법을 사용하여 구성된 모든 MCP 서버에서 검색된 도구에 액세스 .
Python:
app.get_tools()및app.get_tool_schemas()메서드TypeScript:
app.getTools()및app.getToolSchemas()메서드
다음 예제는 원격 MCP 도구를 사용하는 배포 가능한 최소 에이전트 보여줍니다. 에이전트 LangGraph StateGraph를 사용하여 LLM과 MCP 도구 간에 메시지를 라우팅합니다. LLM은 호출할 도구를 결정하고, ToolNode 클래스가 도구 호출을 실행하며, 추가 도구 호출이 필요하지 않을 때까지 결과를 LLM으로 다시 전달합니다.
에이전트의 언어 에 해당하는 탭 선택하여 해당 예시 확인합니다.
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] 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();
agent.yaml 파일 의 language 필드 를 typescript 값으로 설정하고 remote_mcp_ts.github:app 값에서와 같이 내보낸 app 객체 향하도록 entrypoint 필드 점 .
서버 이름 지정 규칙
서버 이름은 mcp.servers 섹션 아래의 키입니다. 이름에는 ASCII가 아닌 문자와 점으로 구분된 이름을 포함하여 인쇄 가능한 UTF-8로 인코딩된 텍스트를 최대 128자까지 포함할 수 있습니다. 이름은 비워 둘 수 없으며 다음 요소를 포함할 수 없습니다.
공백 전용 텍스트
선행 또는 후행 공백
제어, 너비가 0인, BOM(바이트 순서 표시) 또는 양방향 문자
경로 구분자(
/또는\)..
agentengine agent validate 명령은 이러한 규칙에 따라 이름의 유효성을 검사합니다. 자세한 학습 은 구성 유효성 검사를 참조하세요.
MCP 서버 구성 스키마
다음 표에서는 agent.yaml 파일 의 mcp.servers 섹션에서 사용할 수 있는 필드에 대해 설명합니다.
필드 | 유형 | 필수 사항 | 설명 |
|---|---|---|---|
| 객체 | no | 명명된 MCP 서버 연결을 정의합니다. 이 이름은 |
| 문자열 | no | MCP 연결을 위한 전송 프로토콜 . 현재 지원되는 유일한 값은 |
| 문자열 | 네 | 원격 MCP 서버 엔드포인트의 URL . 절대 |
| map[문자열, 문자열] | no | MCP 서버 에 대한 모든 요청 에 포함할 정적 HTTP headers . 사용 가능한 도구 세트 필터링과 같은 서버별 옵션에 이 옵션을 사용합니다. |
| 문자열 | no | 인증 유형입니다. 허용되는 값은 |
| 문자열 |
| 베어러 토큰을 보유하는 환경 변수의 이름입니다. 변수는 |
| 문자열 | no | 요청 공백으로 구분된 OAuth 범위입니다. 이 필드 |
| 문자열 | no | OAuth 클라이언트 의 사람이 읽을 수 있는 이름입니다. 일부 서버는 권한 부여 동의 화면에 이 이름을 표시합니다. 이 필드 |
| 문자열 | no | 대화형 OAuth 로그인에 사용되는 루프백 리디렉션 URI입니다. 이 필드 |
| 문자열 | 예, | OAuth 클라이언트 ID 보유하는 환경 변수의 이름입니다. |
| 문자열 | 예, | OAuth 클라이언트 시크릿을 보유하는 환경 변수의 이름입니다. |
| 문자열 | no | 클라이언트 자격 증명 인증 위한 액세스 토큰을 요청 데 사용되는 OAuth 토큰 엔드포인트입니다. 절대 |
| list[string] | no | 에이전트 에 노출할 원격 MCP 도구 이름의 허용 목록입니다. 설정하다 하면 플랫폼은 나열된 도구만 등록하고 서버 반환하는 다른 모든 도구는 무시합니다. 생략하면 플랫폼은 서버 반환하는 모든 도구를 노출합니다. 이 필드 사용하여 도구 표면을 에이전트 에 필요한 도구로만 제한할 수 있습니다. |
| int | no | 각 MCP 도구 호출에 적용되는 요청 시간 제한(초)입니다. 기본값은 |
여러 MCP 서버 연결
단일 agent.yaml 파일 의 mcp.servers 섹션 내에서 여러 서버를 정의할 수 있습니다. Atlas Agent Engine은 스타트업 시 구성된 모든 서버에 연결하고 해당 서버의 도구를 에이전트의 도구 표면에 병합합니다. 다음 예시 단일 agent.yaml 파일 에서 GitHub, Sentry 및 Glean 서버를 동시에 연결합니다.
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 인증 사용하여 여러 서버에 연결하는 경우, 환경을 시작하기 전에 각 OAuth 서버 에 대해 agentengine dev mcp auth login <name> 명령을 실행 해야 합니다. 다음 예시 환경을 시작하기 전에 에이전트 프로젝트 디렉토리 에서 실행 Sentry 및 Glean 서버 모두에서 인증하는 명령을 보여줍니다.
agentengine dev mcp auth login sentry agentengine dev mcp auth login glean agentengine dev up
배포를 위한 MCP 자격 증명 프로비저닝
.env 파일 과 로컬 OAuth 토큰 캐시 agentengine dev up 명령을 사용한 로컬 개발 중에만 사용할 수 있습니다. 에이전트 를 배포 전에 배포된 런타임이 각 MCP 서버 에서 인증할 수 있도록 MCP 자격 증명 작업 공간 비밀로 프로비저닝해야 합니다.
다음 섹션에서는 각 인증 유형에 대한 시크릿을 프로비저닝하는 방법을 설명합니다. 프로비저닝 시크릿에 대해 자세히 학습 클라우드 시크릿 프로비저닝 가이드 참조하세요.
베어러 토큰 인증
베어러로 인증된 각 서버 에 대해 토큰 환경 변수를 작업 공간 시크릿으로 프로비저닝합니다. 다음 명령을 사용하여 시크릿을 프로비저닝하고 현재 작업 공간을 대상으로 하는 --workspace-scope 플래그를 포함합니다:
agentengine secret set GITHUB_MCP_TOKEN --workspace-scope
한 단계로 시크릿을 프로비저닝하고 실행 배포서버에 동기화 하려면 --sync 플래그를 사용하세요.
agentengine secret set GITHUB_MCP_TOKEN --workspace-scope --sync
배포하기 전에 무기명으로 인증된 각 서버 에 대해 이 명령을 실행합니다.
OAuth 인증
각 OAuth 서버 에 대해 agentengine dev mcp auth upload 명령을 사용하여 로컬 토큰 캐시 작업 공간에 업로드합니다.
agentengine dev mcp auth upload sentry
실행 배포를 한 번에 업로드하고 동기화 하려면 --sync 플래그를 사용하세요.
agentengine dev mcp auth upload sentry --sync
배포하기 전에 각 OAuth 서버 에 대해 이 명령을 실행합니다.
다음 단계
에이전트 가 원격 MCP 서버에 연결되면 로컬에서 테스트한 다음 배포 할 수 있습니다. 에이전트 를 로컬에서 테스트하고 배포하는 방법에 대해 자세히 학습 Atlas Agent Engine 설명서에서 다음 가이드를 참조하세요.