MCP
에이전트를 외부 도구 및 서비스와 연결하기 위한 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-6-astra'
});
// 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-6-astra',
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 통합은 보안과 단순성을 유지하면서 강력한 외부 도구 접근을 제공합니다.