MCP 서버에 연결하기

MCP 서버에 연결하기

원격 MCP 서버에서 관리형 딥 에이전트에 도구를 추가할 수 있어요.

관리형 딥 에이전트를 원격 Model Context Protocol (MCP) 서버에 연결해 그 도구를 에이전트에 추가합니다. Managed Deep Agents가 MCP 클라이언트를 만들고 도구를 로드합니다.

대부분의 원격 MCP 서버는 인증이 필요합니다. 연결(connection)이 인증을 제공하며, 연결을 사용자 소유로 선언하면 각 호출자가 자신의 계정을 승인하게 됩니다.

Managed Deep Agents는 공개 베타 상태이며 LangSmith Cloud의 미국 지역에서만 사용할 수 있어요.

MCP 서버를 tools/mcp.ts에 선언합니다:

my-agent/
  agent.ts
  tools/
    mcp.ts

전체 프로젝트 레이아웃은 프로젝트 구조를 참고하세요.

대신 프로젝트에서 애플리케이션 로직을 구현하려면 작성된 도구(authored tool)를 사용하세요.

출처: 문서

본문

MCP 서버 추가하기 (Add MCP servers)

도구가 이미 원격 MCP 서버에 있고, 에이전트 정의로 가져오지 않고 MDA가 로드하도록 하려면 MCP 서버를 사용하세요.

서버 선언하기 (Declare the servers)

defineMcp를 사용해 하나 이상의 원격 서버를 선언합니다:

import { defineMcp } from "managed-deepagents";

export const mcp = defineMcp({
  servers: {
    langchainDocs: {
      transport: "http",
      url: "https://docs.langchain.com/mcp",
    },
  },
});

모듈은 이름이 mcp인 것을 내보내야 합니다. 프로젝트에는 하나의 MCP 선언이 있으므로 모든 서버를 그 안에 선언하세요. 파일 이름은 .tsx, .mts, .cts 변형도 허용합니다.

Managed Deep Agents는 Streamable HTTP("http") 및 레거시 SSE("sse") 전송을 지원합니다. Stdio MCP 서버는 지원되지 않습니다. 대신 stdio 서버를 HTTP로 노출하거나 그 운영을 작성된 도구로 구현하세요.

연결 옵션은 연결 관리를 참고하세요.

도구 선택하기 (선택) (Select tools (Optional))

기본적으로 Managed Deep Agents는 각 서버의 모든 도구를 노출합니다. 선택한 도구만 노출하려면 해당 서버 구성 내에 허용 목록을 설정하세요:

{
  transport: "http",
  url: "https://docs.langchain.com/mcp",
  includeTools: ["search_docs_by_lang_chain"],
}

선택한 도구를 제외한 모든 도구를 노출하려면 includeTools를 excludeTools로 바꾸세요.

두 옵션을 함께 사용할 수 있습니다. 차단 목록은 허용 목록 후에 적용되며, 같은 도구가 두 목록에 모두 나타날 수는 없습니다.

선택은 Managed Deep Agents가 도구 이름에 접두사를 붙이기 전의 원시 MCP 도구 이름을 사용합니다. 도구 이름은 충돌을 피하기 위해 기본적으로 서버 이름으로 접두사가 붙습니다. 예를 들어 langchainDocs 서버의 search_docs_by_lang_chain 도구는 langchainDocs__search_docs_by_lang_chain으로 노출됩니다.

자격증명 전달하기 (선택) (Pass credentials (Optional))

MCP 서버에 자격증명이 필요하면 서버 구성에 연결을 선언하고 워크스페이스에서 해당 연결을 만드세요.

  • MCP OAuth: OAuth를 광고하고 자동 클라이언트 등록을 지원하는 서버의 경우 mda connections create <slug>(MCP 선언에서 유추) 또는 mda connections create <slug> --mcp <url>로 만듭니다. 클라이언트 ID 또는 시크릿을 제공하지 않습니다.
  • 불투명 시크릿 또는 일반 OAuth: 정적 API 키 또는 직접 등록하는 BYOT OAuth 앱의 경우 불투명 시크릿 또는 일반 OAuth 연결을 만든 다음 서버의 connection 옵션을 connections.get(...)으로 설정합니다.

생성 모드, 소유자, 런타임 인증은 연결 관리를 참고하세요.

MCP 서버 구성하기 (Configure MCP servers)

각 서버는 다음 핵심 옵션을 지원합니다:

옵션 (Option) 설명 (Description)
transport 필수. Streamable HTTP는 http, 레거시 SSE는 sse를 사용.
url 필수. 원격 MCP 엔드포인트 URL.
headers 서버로 보낼 정적 헤더.
include_tools / includeTools 노출할 원시 MCP 도구 이름.
exclude_tools / excludeTools 숨길 원시 MCP 도구 이름.
default_tool_timeout / defaultToolTimeout 각 도구 호출의 타임아웃. Python은 초, TypeScript는 밀리초.
automatic_sse_fallback / automaticSSEFallback HTTP의 경우 클라이언트가 SSE로 폴백하도록 허용.
reconnect SSE의 경우 재연결 동작 구성.

MCP 정의는 다음 옵션도 허용합니다:

옵션 (Option) 기본값 (Default) 설명 (Description)
prefix_tool_name_with_server_name / prefixToolNameWithServerName true 각 도구에 {server}__ 접두사를 붙임.
throw_on_load_error / throwOnLoadError true 부분 도구 세트로 시작하는 대신 로딩을 실패 처리.

배포 (Deployment)

mda dev와 mda deploy는 tools/ 아래의 MCP 선언을 발견하고 관리 구성에 포함합니다. 선언은 Context Hub에 동기화되지 않습니다.

MCP 커넥터를 사용할 때 (When to use MCP connectors)

개념 (Concept) 종류 (Kind) 에이전트에 도달하는 방식 (How it reaches the agent)
MCP 서버 (MCP servers) 관리 구성 tools/ 아래의 MCP 모듈에 선언; 에이전트 진입점으로 가져오지 않음
MCP 엔드포인트 배포 API 에이전트를 MCP 클라이언트에 도구로 노출
작성된 도구 (Authored tools) 애플리케이션 코드 에이전트 정의에 가져와 전달
채널 (Channels) 관리 구성 에이전트 실행을 시작하고 응답을 전달하는 외부 메시지 수신

자세한 내용은 프로젝트 구조를 참고하세요.

더 알아보기 (Learn more)