AI 에이전트의 경우: 문서 인덱스는 https://www.mongodb.com/ko-kr/docs/llms.txt에서 사용할 수 있으며, 모든 페이지의 마크다운 버전은 어떤 URL 경로에 .md를 추가하여 사용할 수 있습니다.
See how MongoDB 9.0 delivers up to 2x higher throughput.
MongoDB Branding Shape
Register now >
Docs Menu

원격 MCP 서버 사용

이 가이드 에서는 에이전트 를 원격 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 인증 서버 에 연결할 수 있습니다.

시작하기 전에 다음 항목이 준비되어 있는지 확인하세요.

  • agentengine CLI 설치되고 인증되었습니다. 자세한 학습 은 설치 및 인증 가이드 참조하세요.

  • agent.yaml 파일 있는 유효한 에이전트 프로젝트 . 자세히 학습 프로젝트 만들기 가이드 참조하세요.

  • 원격 MCP 서버 의 자격 증명: 베어러 토큰 인증 위한 개인 액세스 토큰 또는 OAuth 인증 위한 OAuth 액세스 이 있는 계정.

MCP 서버 정적 개인 액세스 토큰을 허용하는 경우 베어러 토큰 인증 사용합니다.

1

Add the bearer token to your .env file with the variable name you will reference in the agent.yaml file. The following example shows how to add a token to your .env file:

GITHUB_MCP_TOKEN=<your-personal-access-token>

중요

버전 관리에 시크릿을 커밋 하지 마세요. .env 파일 .gitignore 파일 에 추가합니다.

2

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
3

에이전트 프로젝트 디렉토리 에서 다음 명령을 실행 . 이 플랫폼은 스타트업 시 MCP 서버 에 연결되고 도구를 자동으로 등록합니다.

agentengine dev up

MCP 서버 OAuth 2를 지원할 때 OAuth 인증 사용합니다.1. 에이전트 스택 시작하기 전에 agentengine dev mcp auth login 명령을 실행 토큰 캐시 채워야 합니다.

1

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
2

에이전트 프로젝트 디렉토리 에서 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 명령을 실행 해야 합니다. 런타임은 스타트업 시 토큰 캐시 마운트하며 환경이 실행 후에는 인증할 수 없습니다.

3

에이전트 프로젝트 디렉토리 에서 다음 명령을 실행 . 이 플랫폼은 MCP 서버 에 연결하고 해당 도구를 자동으로 등록합니다.

agentengine dev up

원격 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]
@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();

agent.yaml 파일 의 language 필드 를 typescript 값으로 설정하고 remote_mcp_ts.github:app 값에서와 같이 내보낸 app 객체 향하도록 entrypoint 필드 점 .

서버 이름은 mcp.servers 섹션 아래의 키입니다. 이름에는 ASCII가 아닌 문자와 점으로 구분된 이름을 포함하여 인쇄 가능한 UTF-8로 인코딩된 텍스트를 최대 128자까지 포함할 수 있습니다. 이름은 비워 둘 수 없으며 다음 요소를 포함할 수 없습니다.

  • 공백 전용 텍스트

  • 선행 또는 후행 공백

  • 제어, 너비가 0인, BOM(바이트 순서 표시) 또는 양방향 문자

  • 경로 구분자(/ 또는 \)

  • ..

agentengine agent validate 명령은 이러한 규칙에 따라 이름의 유효성을 검사합니다. 자세한 학습 은 구성 유효성 검사를 참조하세요.

다음 표에서는 agent.yaml 파일 의 mcp.servers 섹션에서 사용할 수 있는 필드에 대해 설명합니다.

필드
유형
필수 사항
설명

mcp.servers.<name>

객체

no

명명된 MCP 서버 연결을 정의합니다. 이 이름은 agentengine dev mcp auth login <name> 명령을 실행 때 서버 식별자로 사용됩니다. 이름 지정 요구 사항을 보려면 서버 이름 지정 규칙 섹션을 참조하세요.

mcp.servers.<name>.transport

문자열

no

MCP 연결을 위한 전송 프로토콜 . 현재 지원되는 유일한 값은 streamable_http입니다. 이는 기본값 이기도 합니다.

mcp.servers.<name>.url

문자열

네

원격 MCP 서버 엔드포인트의 URL . 절대 http 또는 https URL 지정해야 합니다. auth.type 필드 none 이외의 값으로 설정하다 경우 URL https를 사용해야 합니다.

mcp.servers.<name>.headers

map[문자열, 문자열]

no

MCP 서버 에 대한 모든 요청 에 포함할 정적 HTTP headers . 사용 가능한 도구 세트 필터링과 같은 서버별 옵션에 이 옵션을 사용합니다.

mcp.servers.<name>.auth.type

문자열

no

인증 유형입니다. 허용되는 값은 none, bearer_env, oauth 및 client_credentials입니다. 기본값은 none입니다.

mcp.servers.<name>.auth.token_env

문자열

auth.type 이 bearer_env인 경우

베어러 토큰을 보유하는 환경 변수의 이름입니다. 변수는 .env 파일 에서 설정하다 해야 합니다.

mcp.servers.<name>.auth.scope

문자열

no

요청 공백으로 구분된 OAuth 범위입니다. 이 필드 auth.type이 oauth 또는 client_credentials로 설정하다 경우에만 설정하다 수 있습니다.

mcp.servers.<name>.auth.client_name

문자열

no

OAuth 클라이언트 의 사람이 읽을 수 있는 이름입니다. 일부 서버는 권한 부여 동의 화면에 이 이름을 표시합니다. 이 필드 auth.type이 oauth로 설정하다 경우에만 설정하다 수 있습니다.

mcp.servers.<name>.auth.redirect_uri

문자열

no

대화형 OAuth 로그인에 사용되는 루프백 리디렉션 URI입니다. 이 필드 auth.type이 oauth로 설정하다 경우에만 설정하다 수 있습니다.

mcp.servers.<name>.auth.client_id_env

문자열

예, auth.type가 client_credentials로 설정하다 경우

OAuth 클라이언트 ID 보유하는 환경 변수의 이름입니다.

mcp.servers.<name>.auth.client_secret_env

문자열

예, auth.type가 client_credentials로 설정하다 경우

OAuth 클라이언트 시크릿을 보유하는 환경 변수의 이름입니다.

mcp.servers.<name>.auth.token_url

문자열

no

클라이언트 자격 증명 인증 위한 액세스 토큰을 요청 데 사용되는 OAuth 토큰 엔드포인트입니다. 절대 https URL 지정해야 합니다. 이 필드 auth.type이 client_credentials인 경우에만 설정하다 수 있습니다.

mcp.servers.<name>.allowed_tools

list[string]

no

에이전트 에 노출할 원격 MCP 도구 이름의 허용 목록입니다. 설정하다 하면 플랫폼은 나열된 도구만 등록하고 서버 반환하는 다른 모든 도구는 무시합니다. 생략하면 플랫폼은 서버 반환하는 모든 도구를 노출합니다. 이 필드 사용하여 도구 표면을 에이전트 에 필요한 도구로만 제한할 수 있습니다.

mcp.servers.<name>.timeout_seconds

int

no

각 MCP 도구 호출에 적용되는 요청 시간 제한(초)입니다. 기본값은 30입니다.

단일 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

.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 서버 에 대해 agentengine dev mcp auth upload 명령을 사용하여 로컬 토큰 캐시 작업 공간에 업로드합니다.

agentengine dev mcp auth upload sentry

실행 배포를 한 번에 업로드하고 동기화 하려면 --sync 플래그를 사용하세요.

agentengine dev mcp auth upload sentry --sync

배포하기 전에 각 OAuth 서버 에 대해 이 명령을 실행합니다.

에이전트 가 원격 MCP 서버에 연결되면 로컬에서 테스트한 다음 배포 할 수 있습니다. 에이전트 를 로컬에서 테스트하고 배포하는 방법에 대해 자세히 학습 Atlas Agent Engine 설명서에서 다음 가이드를 참조하세요.