CrestApp Mcp (client or server) flow

In the CrestApps Orchard Core project, the integration of Prompts and Resources via the Model Context Protocol (MCP) depends on whether Orchard Core is acting as the Client (consuming external prompts/resources) or the Server (exposing its internal data as prompts/resources).

Here is the sequence and flow for both scenarios.

Scenario A: Orchard Core as an MCP Client

(Flow: An Orchard Core AI Agent uses an external MCP server's prompts and resources)

When you chat with an AI Agent in Orchard Core that is connected to an external MCP Server (e.g., a local Python script or a remote database server), the system orchestrates the context building before sending the request to the LLM.

Sequence Flow:

1. User Input: The user sends a chat message to the Orchard Core AI Agent.
2. Context Building Initiation: The Orchard Core DefaultOrchestrator triggers the context-building phase (IAICompletionContextBuilder).
3. Capability Resolution: The IMcpCapabilityResolver checks the attached MCP connections (SSE or STDIO) and asks the remote MCP Server for its capabilities (Tools, Prompts, Resources).
4. Resource Retrieval (Optional):
   • If the agent determines it needs a specific remote resource (e.g., a remote file or database row exposed by the MCP server), it invokes the resources/read protocol.
   • The remote MCP server returns the raw resource data.
   • The Orchard Core IMcpResourceHandler captures this data and appends it to the LLM's system prompt context.
5. Prompt Retrieval (Optional):
   • If the agent is instructed to use a remote prompt template, it calls prompts/get with required arguments on the remote MCP Server.
   • The external MCP server renders the prompt and returns the text.
   • The McpAICompletionContextBuilderHandler merges this returned text into the final prompt instructions.
6. LLM Execution: Orchard Core sends the fully assembled payload (User Message + MCP Resources Data + MCP Prompt Instructions) to the configured AI Provider (OpenAI, Ollama, etc.).
7. Response: The LLM streams the response back to the Orchard Core UI.

Scenario B: Orchard Core as an MCP Server

(Flow: An external client like Claude Desktop queries Orchard Core for prompts and resources)

In this scenario, you use the Orchard Core Admin UI to define McpPrompt (Liquid templates) and McpResource (Content Items, Files, FTP/SFTP locations). An external AI assistant connects to Orchard Core to consume them.

Sequence Flow:

1. Connection / Handshake:
   • External Client (e.g., Claude) connects to Orchard Core's /api/mcp/sse endpoint.
   • Authentication is handled via McpApiKeyAuthenticationHandler or OAuth2.
2. Discovery (prompts/list & resources/list):
   • The external client asks Orchard Core what it knows.
   • Orchard Core’s IMcpServerPromptService and IMcpServerResourceService query the Orchard Core database and return the catalog of defined Prompts and Resources.
3. Execution - Taking Prompts (prompts/get):
   • Client Request: Claude decides to use a prompt named summarize_article and passes required arguments (e.g., articleId).
   • Server Routing: The request hits Orchard Core's McpPromptHandler.
   • Rendering: Orchard Core evaluates the McpPrompt Liquid template, binds the arguments, accesses internal Orchard Core data if needed, and generates the final text string.
   • Return: The rendered text is sent back to Claude to be used as system instructions.
4. Execution - Taking Resources (resources/read):
   • Client Request: Claude requests a specific URI (e.g., content://article/123 or ftp://server/logs.txt).
   • Server Routing: Orchard Core's McpResourceHandler intercepts the request.
   • Type Delegation: It delegates the fetch to a specific IMcpResourceTypeHandler (e.g., ContentByIdResourceTypeHandler, FtpResourceTypeHandler, or FileResourceTypeHandler).
   • Data Extraction: The handler fetches the physical file, FTP stream, or Orchard Core Content Item JSON.
   • Return: Orchard Core returns the raw data/text to Claude, which Claude then reads to answer the user's question.