MCP Plugin

Relevant source files

• e2e/scenarios/mcp-catalog-sync-ui.test.ts
• e2e/scenarios/mcp-catalog-sync.test.ts
• packages/plugins/google/src/react/AddGoogleSource.tsx
• packages/plugins/graphql/src/react/AddGraphqlSource.tsx
• packages/plugins/mcp/src/api/group.ts
• packages/plugins/mcp/src/api/handlers.test.ts
• packages/plugins/mcp/src/api/handlers.ts
• packages/plugins/mcp/src/react/AddMcpSource.tsx
• packages/plugins/mcp/src/react/EditMcpSource.tsx
• packages/plugins/mcp/src/sdk/__snapshots__/probe-shape-real-servers.live.test.ts.snap
• packages/plugins/mcp/src/sdk/catalog-sync.test.ts
• packages/plugins/mcp/src/sdk/connection.ts
• packages/plugins/mcp/src/sdk/discover.ts
• packages/plugins/mcp/src/sdk/errors.ts
• packages/plugins/mcp/src/sdk/invoke.ts
• packages/plugins/mcp/src/sdk/manifest.ts
• packages/plugins/mcp/src/sdk/plugin.test.ts
• packages/plugins/mcp/src/sdk/plugin.ts
• packages/plugins/mcp/src/sdk/probe-shape-real-servers.live.test.ts
• packages/plugins/mcp/src/sdk/probe-shape.test.ts
• packages/plugins/mcp/src/sdk/probe-shape.ts
• packages/plugins/mcp/src/sdk/types.ts
• packages/plugins/microsoft/src/react/AddMicrosoftSource.tsx
• packages/plugins/openapi/src/react/AddOpenApiSource.tsx

The MCP Plugin integrates the Model Context Protocol (MCP) into the Executor ecosystem. It allows the system to act as an MCP host, discovering tools from remote or local MCP servers and exposing them to agents. The plugin supports multiple transport modes, handles complex authentication discovery via a custom probing engine, and provides a specialized React UI for server registration.

Transport Modes

The plugin supports three primary transport mechanisms to communicate with MCP servers:

1. stdio: Used for local processes. The host spawns a child process and communicates over standard input/output. This mode is restricted in cloud environments (e.g., Cloudflare Workers) and is typically used in the CLI or Desktop hosts packages/plugins/mcp/src/sdk/connection.ts10-16
2. SSE (Server-Sent Events): A web-standard transport where the server pushes events to the client over a long-lived HTTP connection packages/plugins/mcp/src/sdk/connection.ts3
3. streamable-http: A high-performance transport optimized for request-response cycles and streaming bodies packages/plugins/mcp/src/sdk/connection.ts4

Connection Lifecycle

Connections are managed via createMcpConnector packages/plugins/mcp/src/sdk/connection.ts43 In serverless environments, the plugin uses a specialized CfWorkerJsonSchemaValidator instead of the default Ajv to avoid issues with dynamic code generation (new Function) packages/plugins/mcp/src/sdk/connection.ts161-166

Sources: packages/plugins/mcp/src/sdk/connection.ts1-166

Tool Discovery and Catalog Sync

The plugin bridges the gap between the Executor's persistent tool catalog and the dynamic nature of MCP servers.

Discovery Flow

When an MCP integration is added or refreshed, discoverTools is invoked packages/plugins/mcp/src/sdk/discover.ts It performs the following:

1. Handshake: Establishes a connection and performs the initialize JSON-RPC call.
2. Listing: Calls tools/list to retrieve the server's capabilities.
3. Manifest Extraction: Converts the MCP tool definitions into Executor-compatible McpToolManifestEntry objects packages/plugins/mcp/src/sdk/manifest.ts51

Stamped Annotations

To maintain tool identity across the system, the plugin "stamps" tool definitions with an mcp envelope in the annotations field packages/plugins/mcp/src/sdk/plugin.ts143-148 This includes:

• toolName: The original name of the tool on the MCP server.
• upstream: Original hints like readOnlyHint or destructiveHint packages/plugins/mcp/src/sdk/plugin.ts152-160

Freshness and Sync

The system listens for notifications/tools/list_changed from the server packages/plugins/mcp/src/sdk/invoke.ts143-151 When received, it marks the persisted catalog as stale, triggering a re-sync on the next access.

Sources: packages/plugins/mcp/src/sdk/plugin.ts135-170 packages/plugins/mcp/src/sdk/invoke.ts143-151 packages/plugins/mcp/src/sdk/manifest.ts51

Probing and Authentication Discovery

A core feature of the MCP plugin is the probeMcpEndpointShape function packages/plugins/mcp/src/sdk/probe-shape.ts53 This is used during registration to verify if an endpoint is a valid MCP server and determine its authentication requirements.

Probe Logic

The probe performs a non-destructive check by sending an initialize JSON-RPC POST request packages/plugins/mcp/src/sdk/probe-shape.ts46-55 It classifies the response into:

• Unauthenticated MCP: Returns a 2xx status with a valid JSON-RPC envelope packages/plugins/mcp/src/sdk/probe-shape.ts16-22
• Authenticated MCP: Returns a 401 with a WWW-Authenticate: Bearer header and a JSON-RPC error body packages/plugins/mcp/src/sdk/probe-shape.ts23-27
• OAuth Protected (RFC 9728): Checks for path-scoped well-known metadata at /.well-known/oauth-protected-resource packages/plugins/mcp/src/sdk/probe-shape.ts115-131

Discovery Logic Diagram

Sources: packages/plugins/mcp/src/sdk/probe-shape.ts1-150

Elicitation Bridge

The plugin implements a bridge between the MCP elicit capability and the Executor's internal elicitation engine. This allows an MCP tool to pause execution and request additional information from the user (e.g., via a form or URL).

Implementation

1. Handler Installation: During tool invocation, installElicitationHandler is called packages/plugins/mcp/src/sdk/invoke.ts105
2. Request Mapping: Incoming ElicitRequestSchema from the MCP server is decoded into McpElicitParams packages/plugins/mcp/src/sdk/invoke.ts75-89
3. Transformation: It is converted to an Executor ElicitationRequest (either FormElicitation or UrlElicitation) packages/plugins/mcp/src/sdk/invoke.ts93-103
4. Response Handling: The result of the user's interaction is marshaled back into the MCP-compliant action and content format packages/plugins/mcp/src/sdk/invoke.ts114-120

Sources: packages/plugins/mcp/src/sdk/invoke.ts71-133

React UI: AddMcpSource

The AddMcpSource component provides a stateful wizard for registering new MCP integrations packages/plugins/mcp/src/react/AddMcpSource.tsx164

Registration Workflow

1. Transport Selection: User chooses between remote (HTTP/SSE) or stdio packages/plugins/mcp/src/react/AddMcpSource.tsx179
2. Probing: For remote servers, the UI triggers the probeEndpoint API, which uses the backend probing logic described above packages/plugins/mcp/src/react/AddMcpSource.tsx38
3. Identity Derivation: The component automatically suggests a name and slug based on the URL or command packages/plugins/mcp/src/react/AddMcpSource.tsx22-27
4. Auth Configuration: Users can declare authentication templates (API Key, OAuth, or None) using the AuthMethodListEditor packages/plugins/mcp/src/react/AddMcpSource.tsx8-12

UI Data Flow Diagram

Sources: packages/plugins/mcp/src/react/AddMcpSource.tsx74-158 packages/plugins/mcp/src/api/group.ts135-142

API Endpoints

The MCP plugin exposes several management endpoints via the McpGroup packages/plugins/mcp/src/api/group.ts135

Endpoint	Method	Description
/mcp/probe	POST	Triggers the endpoint shape probe packages/plugins/mcp/src/api/group.ts137
/mcp/servers	POST	Registers a new MCP server as an integration packages/plugins/mcp/src/api/group.ts144
/mcp/servers/:slug	GET	Retrieves server configuration and metadata packages/plugins/mcp/src/api/group.ts163
/mcp/servers/:slug/auth	POST	Configures or merges auth templates for the server packages/plugins/mcp/src/api/group.ts178

Sources: packages/plugins/mcp/src/api/group.ts1-185