feat: enhance MCP server with new agent capabilities and documentation updates

Author: omeraplak

examples/with-mcp-server/src/index.ts

@@ -77,6 +77,26 @@ const approvalTool = createTool({
   },
 });
 
+const storyWriter = new Agent({
+  name: "StoryWriterAgent",
+  instructions: "You are a creative story writer.",
+  model: openai("gpt-4o-mini"),
+});
+
+const translatorAgent = new Agent({
+  name: "TranslatorAgent",
+  instructions: "You are a skilled translator.",
+  model: openai("gpt-4o-mini"),
+});
+
+const supervisorAgent = new Agent({
+  name: "SupervisorAgent",
+  instructions:
+    "You are a supervisor agent that delegates tasks to specialized agents. Use the `StoryWriterAgent` agent for creative writing tasks and the `TranslatorAgent` agent for translation tasks. Always choose the most appropriate agent for the given task.",
+  model: openai("gpt-4o-mini"),
+  subAgents: [storyWriter, translatorAgent],
+});
+
 const assistant = new Agent({
   name: "AssistantAgent",
   instructions:
@@ -171,7 +191,7 @@ const mcpServer = new MCPServer({
   protocols: {
     stdio: true,
     http: true,
-    sse: false,
+    sse: true,
   },
   filterTools: ({ items }) => {
     return items;
@@ -248,6 +268,9 @@ const mcpServer = new MCPServer({
 
 new VoltAgent({
   agents: {
+    supervisorAgent,
+    translatorAgent,
+    storyWriter,
     assistant,
   },
   mcpServers: {

examples/with-mcp/src/index.ts

@@ -16,7 +16,7 @@ const mcpConfig = new MCPConfiguration({
     filesystem: {
       type: "stdio",
       command: "npx",
-      args: ["-y", "@modelcontextprotocol/server-filesystem", path.resolve("./data")],
+      args: ["-y", "mcp-remote", "http://localhost:3141/mcp/voltagent-example/mcp"],
     },
   },
 });

packages/core/src/voltagent.ts

@@ -8,7 +8,6 @@ import type { Agent } from "./agent/agent";
 import { getGlobalLogger } from "./logger";
 import { VoltAgentObservability } from "./observability/voltagent-observability";
 import { AgentRegistry } from "./registries/agent-registry";
-import type { Tool } from "./tool";
 import type { IServerProvider, VoltAgentOptions } from "./types";
 import { checkForUpdates } from "./utils/update";
 import { isValidVoltOpsKeys } from "./utils/voltops-validation";
@@ -463,6 +462,7 @@ export class VoltAgent {
         getAllAgents: () => this.registry.getAllAgents() as any,
         getAgent: (id: string) => this.registry.getAgent(id) as any,
       },
+      getParentAgentIds: (agentId: string) => this.registry.getParentAgentIds(agentId),
       workflowRegistry: {
         getWorkflow: (id: string) => this.workflowRegistry.getWorkflow(id) as any,
         getAllWorkflows: () => this.workflowRegistry.getAllWorkflows() as any,
@@ -480,7 +480,6 @@ export class VoltAgent {
             resumeStepId,
           ),
       },
-      getTools: () => this.collectAllTools() as any,
     } as MCPServerDeps;
   }
 
@@ -524,12 +523,4 @@ export class VoltAgent {
       this.a2aServers.delete(server);
     }
   }
-
-  private collectAllTools(): Tool[] {
-    const tools: Tool[] = [];
-    for (const agent of this.registry.getAllAgents()) {
-      tools.push(...agent.getTools());
-    }
-    return tools;
-  }
 }

packages/internal/src/mcp/registry.ts

@@ -1,5 +1,10 @@
 import type { MCPServerDeps, MCPServerLike, MCPServerMetadata } from "./types";
 
+export interface RegisterOptions {
+  startTransports?: boolean;
+  transportOptions?: Record<string, unknown>;
+}
+
 export class MCPServerRegistry<TServer extends MCPServerLike = MCPServerLike> {
   private readonly servers = new Set<TServer>();
   private readonly idByServer = new Map<TServer, string>();

packages/internal/src/mcp/types.ts

@@ -15,7 +15,7 @@ export interface MCPServerDeps {
     getAllAgents(): unknown[];
   };
   workflowRegistry?: Record<string, unknown>;
-  getTools?: () => unknown[];
+  getParentAgentIds?: (agentId: string) => string[];
   logging?: unknown;
   prompts?: unknown;
   resources?: unknown;

packages/mcp-server/README.md

@@ -16,6 +16,10 @@ pnpm install
 pnpm build --filter @voltagent/mcp-server
 ```
 
+## Agent metadata
+
+When an agent is exposed through MCP, its `purpose` field is used as the MCP tool description. Provide a concise, user-facing explanation in `purpose` so MCP clients display helpful copy. If `purpose` is empty, the adapter falls back to the agent instructions.
+
 ## License
 
 MIT

packages/mcp-server/src/adapters/agent.ts

@@ -17,6 +17,16 @@ interface AgentCallArgs {
 }
 
 function toMcpTool(agent: Agent, name: string): MCPTool {
+  const purpose = typeof agent.purpose === "string" ? agent.purpose.trim() : undefined;
+  const instructions =
+    typeof agent.instructions === "string" ? agent.instructions.trim() : undefined;
+  const description =
+    purpose && purpose.length > 0
+      ? purpose
+      : instructions && instructions.length > 0
+        ? instructions
+        : `VoltAgent agent ${agent.name}`;
+
   const inputSchema = {
     type: "object",
     properties: {
@@ -49,7 +59,7 @@ function toMcpTool(agent: Agent, name: string): MCPTool {
   return {
     name,
     title: agent.name,
-    description: agent.purpose ?? `VoltAgent agent ${agent.name}`,
+    description,
     inputSchema: inputSchema as MCPTool["inputSchema"],
     annotations: {
       title: agent.name,

packages/mcp-server/src/server.ts

@@ -739,14 +739,6 @@ export class MCPServer {
     return this.deps;
   }
 
-  private collectToolsFromAgents(agents: Agent[]): Tool[] {
-    const tools: Tool[] = [];
-    for (const agent of agents) {
-      tools.push(...agent.getTools());
-    }
-    return tools;
-  }
-
   private normalizeConfiguredAgents(agents: Record<string, Agent>): Agent[] {
     const map = new Map<string, Agent>();
     for (const agent of Object.values(agents)) {
@@ -886,7 +878,15 @@ export class MCPServer {
       }
     }
     const combinedAgents = Array.from(agentMap.values());
-    const filteredAgents = this.getAgentFilter()({ items: combinedAgents, context });
+    const topLevelAgents = combinedAgents.filter((agent) => {
+      if (!agent.id || !deps.getParentAgentIds) {
+        return true;
+      }
+      const parents = deps.getParentAgentIds(agent.id);
+      return !parents || parents.length === 0;
+    });
+
+    const filteredAgents = this.getAgentFilter()({ items: topLevelAgents, context });
 
     const registeredWorkflows = deps.workflowRegistry.getAllWorkflows();
     const workflowSource = new Map<string, RegisteredWorkflow>();
@@ -930,25 +930,8 @@ export class MCPServer {
       }
     }
 
-    const collectedTools = this.collectToolsFromAgents(filteredAgents);
     const toolById = new Map<string, Tool>();
 
-    for (const tool of collectedTools) {
-      const key = tool.id ?? tool.name;
-      if (key && !toolById.has(key)) {
-        toolById.set(key, tool);
-      }
-    }
-
-    if (deps.getTools) {
-      for (const tool of deps.getTools()) {
-        const key = tool.id ?? tool.name;
-        if (key && !toolById.has(key)) {
-          toolById.set(key, tool);
-        }
-      }
-    }
-
     for (const tool of this.configuredTools) {
       const key = tool.id ?? tool.name;
       if (key && !toolById.has(key)) {

packages/mcp-server/src/types.ts

@@ -121,13 +121,13 @@ export interface MCPServerConfig {
   version: string;
   description?: string;
   protocols?: ProtocolConfig;
-  filterTools?: FilterFunction<VoltTool>;
+  filterTools?: FilterFunction<VoltTool<any, any>>;
   filterAgents?: FilterFunction<Agent>;
   filterWorkflows?: FilterFunction<WorkflowSummary>;
   capabilities?: MCPServerCapabilitiesConfig;
   agents?: Record<string, Agent>;
   workflows?: Record<string, MCPWorkflowConfigEntry>;
-  tools?: Record<string, VoltTool>;
+  tools?: Record<string, VoltTool<any, any>>;
   releaseDate?: string;
   packages?: MCPServerPackageInfo[];
   remotes?: MCPServerRemoteInfo[];
@@ -208,7 +208,7 @@ export interface MCPServerDeps extends BaseMCPServerDeps {
       error?: unknown;
     } | null>;
   };
-  getTools?: () => VoltTool[];
+  getParentAgentIds?: (agentId: string) => string[];
   logging?: MCPLoggingAdapter;
   prompts?: MCPPromptsAdapter;
   resources?: MCPResourcesAdapter;

website/docs/agents/mcp/mcp-server.md

@@ -42,6 +42,8 @@ export const mcpServer = new MCPServer({
 });
 ```
 
+> 📘 **Tip:** When you expose agents through MCP, their `purpose` field becomes the tool description shown in clients. Keep it short and user-facing (fallback is the agent instructions if `purpose` is empty).
+
 This minimal configuration:
 
 - Names the server `voltagent-example` (used in URLs and IDE listings).
@@ -112,7 +114,9 @@ const statusTool = createTool({
 
 const supportAgent = new Agent({
   name: "Support Agent",
-  instructions: "Route customer tickets to the correct queue.",
+  purpose: "Route customer tickets to the correct queue.",
+  instructions:
+    "Use internal knowledge to triage customer tickets and respond with routing guidance.",
   model: openai("gpt-4o-mini"),
   tools: [statusTool],
 });