MCP 개요

Model Context Protocol (MCP)은 AI 모델이 외부 도구와 리소스를 발견하고 상호작용할 수 있도록 설계된 오픈 표준입니다. AI 에이전트를 위한 범용 플러그인 시스템으로 생각하면 됩니다. 에이전트가 어떤 언어로 작성되었거나 어디에 호스팅되어 있든 관계없이 도구를 사용할 수 있게 해줍니다.

Mastra는 MCP를 사용하여 에이전트를 외부 도구 서버에 연결합니다.

MCP 클라이언트로 서드파티 도구 사용하기

Mastra는 MCPClient 클래스를 제공하여 하나 이상의 MCP 서버에 대한 연결을 관리하고 해당 도구에 액세스할 수 있습니다.

설치

아직 설치하지 않았다면 Mastra MCP 패키지를 설치하세요:

Copynpm install @mastra/mcp@latest

MCP 서버 등록

MCP 서버를 Mastra에 등록하여 logging을 활성화하고 구성된 도구 및 통합에 액세스할 수 있도록 합니다

src/mastra/index.ts:

Copyimport { Mastra } from "@mastra/core";
import { myMcpServer } from "./mcpServers";

export const mastra = new Mastra({
  mcpServers: { myMcpServer },
});

MCPClient 구성

연결하려는 서버 맵으로 MCPClient를 구성합니다. subprocess(Stdio) 또는 HTTP(SSE 폴백이 있는 스트리밍 HTTP)를 통한 연결을 지원합니다.

Copyimport { MCPClient } from "@mastra/mcp";

const mcp = new MCPClient({
  servers: {
    // Stdio 예시
    sequential: {
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-sequential-thinking"],
    },
    // HTTP 예시
    weather: {
      url: new URL("http://localhost:8080/mcp"),
      requestInit: {
        headers: {
          Authorization: "Bearer your-token",
        },
      },
    },
  },
});

자세한 구성 옵션은 MCPClient 참조 문서를 참조하세요.

정적 vs 동적 도구 구성

MCPClient는 연결된 서버에서 도구를 검색하는 두 가지 접근 방식을 제공하며, 다양한 애플리케이션 아키텍처에 적합합니다:

정적 구성 (getTools())

구성된 모든 서버에 있는 모든 도구를 가져옵니다. 도구 구성(API 키와 같은)이 정적이고 모든 사용자나 요청에서 공유될 때 가장 적합합니다. 일반적으로 이를 한 번 호출하고 Agent를 정의할 때 tools 속성에 결과를 전달합니다. 참조:getTools()

Copyimport { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
import { MCPClient } from "@mastra/mcp";

// MCP 클라이언트 생성
const mcp = new MCPClient({
  servers: {
    filesystem: {
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"],
    },
    weather: {
      command: "npx", 
      args: ["-y", "weather-mcp-server"],
    },
  },
});

// 모든 연결된 서버에서 도구 가져오기
const tools = await mcp.getTools();

// 도구로 에이전트 생성
const agent = new Agent({
  name: "MCP 도구가 있는 에이전트",
  instructions: "연결된 MCP 서버의 도구를 사용할 수 있습니다.",
  model: openai("gpt-4o-mini"),
  tools: tools, // 모든 MCP 도구 포함
});

// 에이전트 사용
const response = await agent.generate("현재 디렉토리의 파일을 나열해주세요.");

동적 구성 (getToolsets())

요청별로 또는 사용자별로 구성이 변경될 수 있는 시나리오를 위해 설계되었습니다(예: 다중 사용자 애플리케이션에서 서로 다른 테넌트를 위한 서로 다른 API 키). getToolsets()의 결과를 에이전트의 generate() 또는 stream() 메서드의 toolsets 옵션에 전달합니다. 참조:getToolsets()

Copyimport { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
import { MCPClient } from "@mastra/mcp";

// 기본 MCP 클라이언트 생성 (서버 없음)
const mcp = new MCPClient({
  servers: {},
});

// API 핸들러에서 사용자별 구성
async function handleUserRequest(userId: string, userToken: string, message: string) {
  // 사용자별 서버 구성
  const userServers = {
    [`user-${userId}-filesystem`]: {
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-filesystem", `/users/${userId}/documents`],
    },
    [`user-${userId}-database`]: {
      url: new URL("https://api.example.com/mcp"),
      requestInit: {
        headers: {
          Authorization: `Bearer ${userToken}`,
          "X-User-ID": userId,
        },
      },
    },
  };

  // 이 요청에 대한 도구 가져오기
  const toolsets = await mcp.getToolsets(userServers);

  // 사용자별 도구로 에이전트 생성
  const agent = new Agent({
    name: `사용자 ${userId}를 위한 에이전트`,
    instructions: "당신은 사용자별 도구에 액세스할 수 있는 개인 어시스턴트입니다.",
    model: openai("gpt-4o-mini"),
    tools: toolsets, // 이 사용자를 위한 도구만 포함
  });

  return await agent.generate([{ role: "user", content: message }]);
}

MCP 레지스트리에 연결하기

MCP 서버는 레지스트리를 통해 발견할 수 있습니다. 다음은 MCPClient를 사용하여 인기 있는 일부 서버에 연결하는 방법입니다:

Copyimport { MCPClient } from "@mastra/mcp";
 
const mcp = new MCPClient({
  servers: {
    salesforce: {
      url: new URL("https://salesforce-mcp-server.klavis.ai/mcp/?instance_id={private-instance-id}"),
    },
    hubspot: {
      url: new URL("https://hubspot-mcp-server.klavis.ai/mcp/?instance_id={private-instance-id}"),
    },
  },
});

MCP 서버와 도구 공유하기

2025년 7월 26일 기준 번역
by dongne.lab@gmail.com