@voltagent/mcp-server

Provides a standardized MCP server implementation that handles protocol initialization, message routing, and connection lifecycle according to the Model Context Protocol specification. The server manages bidirectional communication channels between MCP clients and exposes agents/tools/workflows as MCP resources, handling serialization/deserialization of protocol messages and maintaining connection state throughout the session.

Wraps VoltAgent agents as MCP resources that can be discovered and invoked by remote MCP clients. The server registers each agent with its configuration, capabilities, and execution parameters, allowing clients to query agent metadata and trigger agent execution with streaming or batch result handling. Agents maintain their internal state and decision-making logic while becoming accessible through the standardized MCP interface.

Registers tools with JSON Schema definitions that describe their inputs, outputs, and constraints, making them discoverable and callable through the MCP protocol. The server implements the MCP tool-calling interface, accepting tool invocation requests from clients, routing them to the appropriate tool implementations, and returning results with proper error handling and type validation. Supports both synchronous and asynchronous tool execution with timeout management.

Exposes VoltAgent workflows as MCP resources that clients can discover and execute. The server manages workflow state, step execution, branching logic, and result aggregation, allowing remote clients to trigger workflows and monitor their progress. Workflows maintain their internal orchestration logic (sequential steps, parallel execution, conditional branches) while becoming accessible through the MCP interface with support for long-running operations and progress reporting.

Implements MCP's resource listing and metadata endpoints, allowing clients to discover all available agents, tools, and workflows with their capabilities, constraints, and usage documentation. The server maintains a registry of all exposed resources and responds to discovery queries with structured metadata including descriptions, input/output schemas, and execution requirements. Supports filtering and searching across resource types.

Implements MCP's streaming capabilities for long-running operations, allowing agents and workflows to send results incrementally as they become available rather than waiting for complete execution. The server manages streaming connections, handles backpressure, and supports both text and structured data streaming. Clients can receive partial results, progress updates, and intermediate outputs in real-time without blocking on full completion.

Implements comprehensive error handling for tool execution, agent invocation, and workflow execution, returning structured error responses with error codes, messages, and context. The server catches execution failures, timeouts, validation errors, and resource unavailability, translating them into MCP-compliant error responses. Supports error recovery strategies like retries and fallbacks, with detailed logging for debugging.

Validates tool inputs against their JSON Schema definitions before execution, ensuring type safety and constraint compliance. The server performs schema validation on all incoming requests, rejecting invalid inputs with detailed validation error messages that help clients understand what went wrong. Supports custom validators and constraint checking beyond basic JSON Schema validation.

Manages multiple concurrent MCP client connections, maintaining separate session state for each client while sharing access to the same agents, tools, and workflows. The server handles connection lifecycle (connect, authenticate, disconnect), routes messages to appropriate handlers, and manages resource access control. Supports connection pooling and load distribution for high-concurrency scenarios.

Allows configuration of server behavior, resource exposure, execution parameters, and logging through configuration files or environment variables. The server supports different configuration profiles for development, staging, and production environments, with the ability to customize timeouts, resource limits, logging levels, and which agents/tools/workflows are exposed. Configuration can be updated without restarting the server in some cases.