@ag-ui/mcp-apps-middleware

Bridges MCP (Model Context Protocol) servers and AG-UI by wrapping MCP tool definitions into a middleware layer that exposes server capabilities as UI-enabled tools. The middleware intercepts MCP tool schemas, transforms them into UI-compatible representations, and manages the request/response lifecycle between the UI layer and MCP servers, enabling tools to render custom interfaces rather than plain text I/O.

Manages persistent connections to multiple MCP servers with automatic connection pooling, health checking, and graceful reconnection logic. The middleware maintains a registry of active server connections, monitors their health status, and handles connection failures by implementing exponential backoff retry strategies and fallback mechanisms, ensuring reliable tool availability across server restarts or network interruptions.

Transforms raw MCP tool schemas (JSON-RPC format) into AG-UI-compatible schema representations by injecting UI-specific metadata such as component type hints, layout directives, validation rules, and rendering preferences. The transformation pipeline parses MCP schema definitions, maps parameter types to AG-UI form components, and enriches schemas with display hints (labels, descriptions, field ordering) that enable automatic UI generation without manual component authoring.

Routes tool invocation requests from the AG-UI layer through the middleware to the appropriate MCP server, marshals parameters according to the MCP schema, executes the RPC call, and transforms the response back into a format suitable for UI rendering. The routing layer maintains a tool-to-server registry, validates input parameters against the transformed schema, handles RPC errors with user-friendly messages, and ensures response data is properly typed for downstream UI components.

Automatically discovers available tools and capabilities from connected MCP servers by querying their tool list endpoints, builds an in-memory registry of tool definitions indexed by tool ID and server, and exposes this registry to the AG-UI layer for dynamic tool discovery and UI generation. The discovery process runs at middleware initialization and can be refreshed on-demand, maintaining a canonical source of truth for available tools across all connected servers.

Propagates authentication credentials and authorization context from the AG-UI application layer through the middleware to MCP servers, supporting multiple auth schemes (API keys, OAuth tokens, mTLS certificates) and enforcing authorization policies at the middleware layer. The middleware maintains auth context per user session, validates tool access permissions before routing requests to servers, and handles auth failures with appropriate error responses that guide users to re-authenticate.

Logs all tool invocations, parameters, results, and errors to an audit trail that can be persisted to external storage or queried for compliance and debugging purposes. The logging layer captures execution metadata (timestamp, user, tool ID, server, duration, status), sanitizes sensitive data (credentials, PII) before logging, and provides structured log output compatible with standard logging systems (Winston, Pino, etc.) for integration with monitoring and observability platforms.