Orchardcore AI MCP

Orchard Core MCP (Model Context Protocol) - Prompt Templates

Configure MCP Integration

You are an Orchard Core expert. Generate code, configuration, and recipes for integrating Model Context Protocol (MCP) client and server capabilities into Orchard Core using CrestApps modules.

Guidelines

• The Model Context Protocol (MCP) is an open standard for seamless integration between LLM applications and external tools or data sources.
• The CrestApps MCP module provides both client and server features.
• MCP Client: Connect Orchard Core to external MCP servers using SSE or local client transports, extending AI chat capabilities with external tools.
• MCP Server: Expose Orchard Core AI tools and resources to external MCP-compatible clients (AI agents, IDEs, copilots).
• MCP connections can be configured via the admin UI or recipes.
• MCP server authentication supports OpenId, ApiKey, or None (development only).
• Never use AuthenticationType: "None" in production environments.
• Install CrestApps packages in the web/startup project.
• Always secure API keys using user secrets or environment variables.

MCP Features Overview

MCP Client: Connecting to External MCP Servers

Enabling MCP Client Features

{
  "steps": [
    {
      "name": "Feature",
      "enable": [
        "CrestApps.OrchardCore.AI",
        "CrestApps.OrchardCore.AI.Chat",
        "CrestApps.OrchardCore.AI.Mcp",
        "CrestApps.OrchardCore.OpenAI"
      ],
      "disable": []
    }
  ]
}

Adding a Remote MCP Connection (SSE Transport) via Admin UI

1. Navigate to Artificial Intelligence → MCP Connections.
2. Click Add Connection.
3. Under Server Sent Events (SSE), click Add.
4. Enter connection details:
   • Display Text: A friendly name for the connection.
   • Endpoint: The remote MCP server URL (e.g., https://mcp-server.example.com/).
   • Additional Headers: Supply any required authentication headers.
5. Save the connection.
6. Create or edit an AI profile and select this MCP connection under available tools.

Adding a Remote MCP Connection via Recipe (SSE)

{
  "steps": [
    {
      "name": "McpConnection",
      "connections": [
        {
          "DisplayText": "Remote AI Tools Server",
          "Properties": {
            "SseMcpConnectionMetadata": {
              "Endpoint": "https://mcp-server.example.com/",
              "AdditionalHeaders": {}
            }
          }
        }
      ]
    }
  ]
}

Adding a Local MCP Connection (Stdio Transport)

The Local MCP Client feature enables connections to MCP servers running locally (e.g., in Docker containers) using Standard Input/Output.

Step-by-Step: Connect to a Docker-based MCP Server

1. Install Docker Desktop.
2. Pull the desired MCP Docker image (e.g., mcp/time).
3. Navigate to Artificial Intelligence → MCP Connections.
4. Click Add Connection, then under Standard Input/Output (Stdio), click Add.
5. Enter:
   • Display Text: Global Time Capabilities
   • Command: docker
   • Command Arguments: ["run", "-i", "--rm", "mcp/time"]
6. Save the connection.

Adding a Local MCP Connection via Recipe (Stdio)

{
  "steps": [
    {
      "name": "McpConnection",
      "connections": [
        {
          "DisplayText": "Global Time Capabilities",
          "Properties": {
            "StdioMcpConnectionMetadata": {
              "Command": "docker",
              "Arguments": [
                "run",
                "-i",
                "--rm",
                "mcp/time"
              ]
            }
          }
        }
      ]
    }
  ]
}

Enabling MCP Client with Local Stdio Support

{
  "steps": [
    {
      "name": "Feature",
      "enable": [
        "CrestApps.OrchardCore.AI",
        "CrestApps.OrchardCore.AI.Chat",
        "CrestApps.OrchardCore.AI.Mcp",
        "CrestApps.OrchardCore.AI.Mcp.Stdio",
        "CrestApps.OrchardCore.OpenAI"
      ],
      "disable": []
    }
  ]
}

MCP Server: Exposing Orchard Core as an MCP Endpoint

Enabling MCP Server

{
  "steps": [
    {
      "name": "Feature",
      "enable": [
        "CrestApps.OrchardCore.AI",
        "CrestApps.OrchardCore.AI.Mcp.Server"
      ],
      "disable": []
    }
  ]
}

MCP Server Authentication

The MCP server supports three authentication modes:

Configuring MCP Server Authentication

OpenId (Recommended for production):

{
  "OrchardCore": {
    "CrestApps": {
      "AI": {
        "McpServer": {
          "AuthenticationType": "OpenId",
          "RequireAccessPermission": true
        }
      }
    }
  }
}

When RequireAccessPermission is true, users must have the AccessMcpServer permission.

ApiKey (For simple integrations):

{
  "OrchardCore": {
    "CrestApps": {
      "AI": {
        "McpServer": {
          "AuthenticationType": "ApiKey",
          "ApiKey": "your-secure-api-key-here"
        }
      }
    }
  }
}

The API key can be provided in the Authorization header as: Bearer <key>, ApiKey <key>, or the raw key.

None (Local development only — never use in production):

{
  "OrchardCore": {
    "CrestApps": {
      "AI": {
        "McpServer": {
          "AuthenticationType": "None"
        }
      }
    }
  }
}

MCP Server Endpoint

Endpoints are registered in Startup.Configure via routes.MapMcp("mcp") using the Streamable HTTP transport (WithHttpTransport()), protected by the MCP authorization policy. Paths are relative to the tenant prefix.

Connecting External Clients to Orchard Core MCP Server

Use the Streamable HTTP transport pointing at the /mcp base endpoint. The pinned MCP ASP.NET Core transport maps only that endpoint because legacy SSE is disabled by default.

With OpenId (Streamable HTTP, recommended):

{
  "mcpServers": {
    "orchard-core": {
      "transport": {
        "type": "http",
        "url": "https://your-orchard-site.com/mcp",
        "headers": {
          "Authorization": "Bearer <your-oauth-token>"
        }
      }
    }
  }
}

Exposed Tools via MCP Server

The MCP server automatically exposes all AI tools registered in Orchard Core, including:

• Content Management: Search, create, update, delete, publish/unpublish content (when OrchardCore.Contents is enabled)
• Feature Management: List, enable, disable features (when OrchardCore.Features is enabled)
• User Management: Search users, get user information (when OrchardCore.Users is enabled)
• AI Agent Tools: All tools from the AI Agent module (when CrestApps.OrchardCore.AI.Agent is enabled)

MCP Resources

MCP Resources expose data sources through the MCP protocol. Built-in resource types:

Creating MCP Resources via Recipe

{
  "steps": [
    {
      "name": "McpResource",
      "Resources": [
        {
          "Source": "file",
          "DisplayText": "Application Config",
          "Resource": {
            "Uri": "file://abc123/etc/config.json",
            "Name": "app-config",
            "Description": "Application configuration file",
            "MimeType": "application/json"
          }
        }
      ]
    }
  ]
}

Registering a Custom MCP Resource Type

services.AddCoreAIMcpResourceType<DatabaseResourceTypeHandler>("database", entry =>
{
    entry.DisplayName = S["Database"];
    entry.Description = S["Query data from databases."];
    entry.SupportedVariables =
    [
        new McpResourceVariable("table") { Description = S["The database table name."] },
        new McpResourceVariable("id") { Description = S["The row ID to fetch."] },
    ];
});

Implement the handler:

public sealed class DatabaseResourceTypeHandler : McpResourceTypeHandlerBase
{
    public DatabaseResourceTypeHandler() : base("database") { }

    protected override Task<ReadResourceResult> GetResultAsync(
        McpResource resource,
        IReadOnlyDictionary<string, string> variables,
        CancellationToken cancellationToken)
    {
        variables.TryGetValue("table", out var table);
        variables.TryGetValue("id", out var id);
        // Query the selected row and return a ReadResourceResult.
        return Task.FromResult(new ReadResourceResult());
    }
}

Security Best Practices

• Always use OpenId authentication for MCP server in production.
• Store API keys in user secrets or environment variables, never in source control.
• Grant the AccessMcpServer permission only to trusted users and roles.
• Individual tool invocations respect Orchard Core's permission system.
• MCP server operates within a single tenant context for tenant isolation.
• Rotate API keys periodically when using ApiKey authentication.

Discovering More MCP Servers

Explore MCP-compatible tools at:

• Docker Hub: MCP Images
• MCP.so
• Glama.ai MCP Servers
• MCPServers.org