MCP

Integração do Model Context Protocol para conectar agentes com ferramentas e serviços externos

Integração do Model Context Protocol para conectar agentes com ferramentas e serviços externos

Visão Geral

O MCP (Model Context Protocol) permite que os agentes do Astreus se conectem perfeitamente com ferramentas e serviços externos. Defina servidores MCP como objetos simples com carregamento automático de variáveis de ambiente e use-os em diferentes níveis - agente, tarefa ou conversação.

Definições de Tipo

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 };

Criando Servidores MCP

Defina servidores MCP como objetos de array com carregamento automático de ambiente:

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");

Exemplo

Aqui está um exemplo completo mostrando a integração 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);

Variáveis de Ambiente

Servidores MCP carregam automaticamente variáveis de ambiente do seu arquivo .env:

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

Não é necessário especificar variáveis de ambiente no código - elas são carregadas automática e seguramente.

Tipos de Servidor

Servidores Locais (stdio)

Para servidores que rodam como processos locais:

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

Servidores Remotos (SSE)

Para servidores que se conectam via HTTP/SSE:

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

Uso em Múltiplos Níveis

Nível de Agente

Disponível para todas as tarefas e conversas:

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

Nível de Tarefa

Disponível para tarefas específicas:

// 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"]
    }
  ]
});

Nível de Conversação

Disponível para conversas individuais:

// 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"]
    }
  ]
});

Acesso Manual a Ferramentas

Acesse ferramentas MCP de forma programática:

// 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');

Tipos de Resposta

Resposta do callMCPTool

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
}

Resposta do getMCPTools

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']
    }
  }
]

Referência da API

Métodos MCP do Agente

// 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[]

A integração MCP fornece acesso poderoso a ferramentas externas, mantendo segurança e simplicidade.

Última atualização: 6 de julho de 2026

Nesta seção

Introdução

Framework de agentes de IA open-source para construir sistemas autônomos que resolvem tarefas do mundo real de forma eficaz.

Instalação

Instale o Astreus com npm, yarn ou pnpm, confirme a versão necessária do Node.js e prepare um projeto local para construir agentes de IA com o framework.

Início Rápido

Construa seu primeiro agente de IA com Astreus em menos de 2 minutos Aprenda os padrões de configuração, as APIs e os exemplos práticos necessários para...

Agente

Entidade central de IA com capacidades modulares e composição baseada em decorators Aprenda os padrões de configuração, as APIs e os exemplos práticos...

Plugin

Visão