MCP

에이전트를 외부 도구 및 서비스와 연결하기 위한 Model Context Protocol 통합 안정적인 Astreus 에이전트 시스템을 구축하는 데 필요한 설정 패턴, API, 실용적인 예제를 알아보세요.

에이전트를 외부 도구 및 서비스와 연결하기 위한 Model Context Protocol 통합

Overview

MCP(Model Context Protocol)는 Astreus 에이전트가 외부 도구 및 서비스와 원활하게 연결할 수 있게 합니다. MCP 서버를 자동 환경 변수 로딩이 포함된 간단한 객체로 정의하고 에이전트, 작업, 대화 등 다양한 수준에서 사용하세요.

Type Definitions

MCPServerDefinition

interface MCPServerDefinition {
  name: string;           // Server name for identification (required)
  command?: string;       // Command to execute (for stdio servers)
  args?: string[];        // Command arguments
  env?: Record<string, string>;  // Environment variable overrides
  url?: string;           // URL for SSE servers
  cwd?: string;           // Working directory
}

MCPTool

interface MCPTool {
  name: string;
  description: string;
  inputSchema: MCPJsonSchema;
}

MCPToolResult

interface MCPToolResult {
  content: Array<{
    type: string;
    text?: string;
  }>;
  isError?: boolean;
}

MCPValue

type MCPPrimitive = string | number | boolean | null;
type MCPValue = MCPPrimitive | MCPPrimitive[] | { [key: string]: MCPValue };

Creating MCP Servers

자동 환경 변수 로딩이 포함된 배열 객체로 MCP 서버를 정의하세요.

import { Agent } from '@astreus-ai/astreus';

// Define MCP servers array
const mcpServers = [
  {
    name: 'github',
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-github"]
    // GITHUB_PERSONAL_ACCESS_TOKEN loaded from .env automatically
  },
  {
    name: 'filesystem', 
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Documents"]
  }
];

const agent = await Agent.create({
  name: 'DevAgent',
  model: 'gpt-4'
});

// Add MCP servers to agent
await agent.addMCPServers(mcpServers);

// Use automatically in conversations
const response = await agent.ask("List my repositories and save to repos.txt");

Example

MCP 통합을 보여주는 전체 예제입니다.

import { Agent } from '@astreus-ai/astreus';

// Create agent
const agent = await Agent.create({
  name: 'DevAssistant',
  model: 'gpt-4',
  systemPrompt: 'You are a helpful development assistant with access to various tools.'
});

// Add MCP servers
await agent.addMCPServers([
  {
    name: 'github',
    command: "npx", 
    args: ["-y", "@modelcontextprotocol/server-github"]
  },
  {
    name: 'filesystem',
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
  },
  {
    name: 'search',
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-brave-search"]
  }
]);

// Agent now has access to GitHub, filesystem, and search tools
const response = await agent.ask(`
  Check my latest repositories, 
  create a summary file in my project directory,
  and search for TypeScript best practices
`);

console.log(response);

Environment Variables

MCP 서버는 .env 파일에서 환경 변수를 자동으로 로드합니다.

# .env
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxxxxxxxxx
BRAVE_API_KEY=your_brave_api_key
GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json

코드에서 환경 변수를 지정할 필요가 없습니다. 자동으로 안전하게 로드됩니다.

Server Types

Local Servers (stdio)

로컬 프로세스로 실행되는 서버의 경우:

const localServers = [
  {
    name: 'sqlite',
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-sqlite", "--db-path", "/path/to/db.sqlite"],
    cwd: "/working/directory"
  }
];

Remote Servers (SSE)

HTTP/SSE를 통해 연결하는 서버의 경우:

const remoteServers = [
  {
    name: 'api-server',
    url: "https://api.example.com/mcp/events"
  }
];

Multi-Level Usage

Agent Level

모든 작업과 대화에서 사용할 수 있습니다.

// Agent-level: Available everywhere 
await agent.addMCPServers([
  {
    name: 'filesystem',
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Documents"]
  }
]);

Task Level

특정 작업에서 사용할 수 있습니다.

// Task-level: Available for this task only
const task = await agent.createTask({
  prompt: "Analyze my GitHub repositories",
  mcpServers: [
    {
      name: 'github',
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-github"]
    }
  ]
});

Conversation Level

단일 대화에서 사용할 수 있습니다.

// Conversation-level: Available for this conversation only
const response = await agent.ask("Search for TypeScript news", {
  mcpServers: [
    {
      name: 'search',
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-brave-search"]
    }
  ]
});

Manual Tool Access

MCP 도구에 프로그래밍 방식으로 접근하세요.

// List available MCP tools
const tools: MCPTool[] = agent.getMCPTools();
console.log('Available MCP tools:', tools.map(t => t.name));

// Call specific MCP tool
// Tool name format: "server:tool_name" or just "tool_name" (auto-resolves server)
const result: MCPToolResult = await agent.callMCPTool('github:list_repos', {
  owner: 'username'
});

// Remove an MCP server by name (synchronous)
agent.removeMCPServer('github');

Response Types

callMCPTool Response

const result: MCPToolResult = await agent.callMCPTool('github:list_repos', { owner: 'username' });

// Response structure (MCPToolResult):
{
  content: [
    { type: 'text', text: 'Repository list...' }
  ],
  isError?: boolean  // Optional error flag
}

getMCPTools Response

const tools: MCPTool[] = agent.getMCPTools();

// Response structure (MCPTool[]):
[
  {
    name: 'list_repos',           // Tool name without server prefix
    description: 'List repositories for a user',
    inputSchema: {                // MCPJsonSchema
      type: 'object',
      properties: {
        owner: { type: 'string', description: 'Repository owner' }
      },
      required: ['owner']
    }
  }
]

API Reference

Agent MCP Methods

// Add a single MCP server (async)
async addMCPServer(serverDef: MCPServerDefinition): Promise<void>

// Add multiple MCP servers (async)
async addMCPServers(servers: MCPServerDefinition[]): Promise<void>

// Remove an MCP server by name (sync)
removeMCPServer(name: string): void

// Call an MCP tool (async)
async callMCPTool(
  toolName: string,                    // "server:tool" or just "tool"
  args: Record<string, MCPValue>       // Tool arguments
): Promise<MCPToolResult>

// Get all available MCP tools (sync)
getMCPTools(): MCPTool[]

MCP 통합은 보안과 단순성을 유지하면서 강력한 외부 도구 접근을 제공합니다.

마지막 업데이트: 2026년 7월 6일

이 섹션에서

소개

실제 작업을 효과적으로 해결하는 자율 시스템을 구축하기 위한 오픈소스 AI 에이전트 프레임워크입니다. 안정적인 Astreus 에이전트 시스템을 구축하는 데 필요한 설정 패턴, API, 실용적인 예제를 알아보세요.

설치

npm, yarn, pnpm을 사용해 Astreus를 설치하고, 필요한 Node.js 버전을 확인한 다음 프레임워크로 AI 에이전트를 구축할 로컬 프로젝트를 준비합니다.

빠른 시작

Astreus 문서에서 빠른 시작에 대해 알아보고, 에이전트 시스템을 구축하기 위한 설정 안내, API 패턴, 실용적인 예제를 확인하세요. 안정적인 Astreus 에이전트 시스템을 구축하는 데 필요한 설정 패턴, API, 실용적인 예제를 알아보세요.

에이전트

Astreus 문서에서 에이전트에 대해 알아보고, 에이전트 시스템을 구축하기 위한 설정 안내, API 패턴, 실용적인 예제를 확인하세요. 안정적인 Astreus 에이전트 시스템을 구축하는 데 필요한 설정 패턴, API, 실용적인 예제를 알아보세요.

플러그인

비전