Model Context Protocol (MCP) Architecture
Relevant source files
The following files were used as context for generating this wiki page:The Model Context Protocol (MCP) provides a framework for integrating external, language-agnostic tools into the Lucky workflow system. These tools, known as MCP servers, run as separate processes and communicate with the core execution engine, allowing AI agents to perform a wide range of tasks such as web scraping, browser automation, and file system operations. This architecture enables a unified interface for both internal TypeScript functions (Code Tools) and these external MCP tools.
The system is designed to be flexible and robust, with features like configuration-driven setup, per-workflow client caching for session persistence, and comprehensive validation. MCP tools are essential for extending the capabilities of AI agents beyond what is possible with in-process code alone, supporting a rich ecosystem of third-party services and custom-built utilities.
Sources: packages/core/README.md, README.md, packages/tools/README.md
MCP Configuration
MCP servers are defined in a central JSON configuration file, typically named mcp-secret.json. The path to this file is specified by the MCP_SECRET_PATH environment variable. The system also supports a dual environment where UI-based workflows can have their configurations stored in a database and accessed via an API.
Sources: packages/tools/src/mcp/setup.ts:60-68, README.md:104-106
Configuration File Structure
The configuration file contains a root object mcpServers, where each key is the name of an MCP tool and the value is an object specifying how to run the server process.
This diagram illustrates the schema for the MCP configuration file.
An example mcp-secret.json configuration:
{
"mcpServers": {
"tavily": {
"command": "npx",
"args": ["-y", "tavily-mcp"],
"env": {
"TAVILY_API_KEY": "${TAVILY_API_KEY}"
}
},
"firecrawl": {
"command": "npx",
"args": ["-y", "firecrawl-mcp"],
"env": {
"FIRECRAWL_API_KEY": "${FIRECRAWL_API_KEY}"
}
},
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allow"]
}
}
}
Sources: apps/web/src/app/api/ai/artifact/route.ts:50-80, packages/mcp-server/README.md
Configuration Properties
| Property | Type | Description |
|---|---|---|
command | string | The executable command to start the MCP server (e.g., npx, python). |
args | string[] | An array of arguments to pass to the command. |
env | Record<string, any> | (Optional) A key-value map of environment variables for the server process, supporting ${VAR_NAME} substitution. |
Sources: packages/tools/src/mcp/setup.ts:48-54, apps/web/src/app/api/mcp/config/route.ts:13-17
Configuration Loading and Validation
The loadExternalMCPConfig function is responsible for loading and validating the MCP configuration file.
This flowchart shows the process of loading and validating the MCP configuration.
Client Setup and Initialization
The primary function for integrating MCP tools into a workflow node is setupMCPForNode. This function is responsible for spinning up MCP clients for the requested tools and returning a ToolSet compatible with the Vercel AI SDK.
Sources: packages/tools/src/mcp/setup.ts:220-227
setupMCPForNode Function
This function orchestrates the entire setup process, including client caching, configuration resolution, and client creation.
| Parameter | Type | Description |
|---|---|---|
toolNames | MCPToolName[] | An array of MCP tool names to initialize. |
workflowId | string | A unique ID for the workflow invocation, used for client caching. |
configPath | string (optional) | Path to mcp-secret.json, overrides MCP_SECRET_PATH env var. |
opts.toolkits | MCPToolkitMap (optional) | UI-configured toolkits passed from the execution context. |
Sources: packages/tools/src/mcp/setup.ts:220-227
Initialization and Caching Flow
setupMCPForNode uses a caching mechanism to maintain persistent sessions for MCP clients (e.g., to preserve browser state in a Playwright tool). Clients are cached in a Map with a key combining the workflowId and the tool name.
This sequence diagram shows how an MCP client is initialized and cached for a workflow node.
Configuration Resolution Order
When initializing a client, setupMCPForNode resolves the configuration with the following priority:
- Context Toolkits: Checks
opts.toolkitswhich are typically passed from a UI-based configuration. It looks for astdiotransport kind. - Config File: If not found in context toolkits, it falls back to loading the configuration from the
mcp-secret.jsonfile.
If a requested tool is not found in either source, a warning is logged, and the tool is skipped.
Sources: packages/tools/src/mcp/setup.ts:257-280
API-Based Configuration Management
For UI-driven workflows, MCP server configurations are managed via a dedicated API, persisting settings in a database rather than a local JSON file.
Sources: apps/web/src/app/api/mcp/config/route.ts
Endpoints
GET /api/mcp/config: Fetches the current user's enabledstdioMCP server configurations from themcp.user_server_configstable. It merges the public configuration (config_json) with secrets like environment variables (secrets_json).POST /api/mcp/config: Saves a user's complete MCP server configuration. It intelligently handles creating, updating, and deleting server entries in the database.
Sources: apps/web/src/app/api/mcp/config/route.ts:21-81, 87-234
Data Model
The API uses Zod schemas for validation, ensuring that incoming data is correctly structured.
// Validation schema for a single MCP server config
const mcpServerConfigSchema = z.object({
command: z.string().min(1),
args: z.array(z.string()),
env: z.record(z.string()).optional(),
});
// Validation schema for the entire configuration payload
const mcpConfigSchema = z.object({
mcpServers: z.record(z.string(), mcpServerConfigSchema),
lastKnownUpdateAt: z.string().datetime().optional(), // For optimistic concurrency
});
Sources: apps/web/src/app/api/mcp/config/route.ts:12-20
The system also includes an AI-powered endpoint, POST /api/ai/artifact, which can modify MCP configurations based on natural language prompts. This allows for dynamic and intelligent updates to the tool ecosystem.
Sources: apps/web/src/app/api/ai/artifact/route.ts:1-150
Available MCP Tools
The framework supports a variety of pre-configured and custom MCP tools. The following are examples mentioned throughout the codebase and documentation.
| Tool Name | Category | Description |
|---|---|---|
tavily | Web Search | Integrates with the Tavily AI search API. |
firecrawl | Web Scraping | Scrapes websites using the Firecrawl service. |
playwright | Browser | Provides browser automation capabilities via Playwright. |
browserUse | Browser | A generic interface for browser automation tasks. |
filesystem | File System | Allows the AI agent to perform file I/O operations. |
googleScholar | Web Search | Specialized tool for searching Google Scholar. |
proxy | Networking | An HTTP proxy tool. |
github | Development | Integrates with GitHub for repository-related tasks. |
postgres | Database | Provides access to a PostgreSQL database. |
slack | Communication | Integrates with the Slack API. |
Sources: packages/tools/README.md, packages/mcp-server/README.md, apps/web/src/app/api/ai/artifact/route.ts:28-48, packages/tools/src/mcp/tests/mcp-setup.test.ts:70-98
Summary
The Model Context Protocol (MCP) architecture in lucky is a powerful and flexible system for extending AI agent capabilities with external tools. It relies on a straightforward JSON configuration for defining server processes and uses a stdio-based transport for communication. The setupMCPForNode function provides a robust entry point for initializing tools, featuring a per-workflow caching mechanism that ensures session persistence and efficiency. With support for both local file-based configuration and a database-backed API for UI-driven setups, the MCP framework is well-integrated into the broader lucky ecosystem, enabling complex, multi-tool workflows.