# Orchardcore AI MCP Server

> Skill for configuring the CrestApps MCP Server feature in Orchard Core. Covers server authentication, exposing tools, adding MCP prompts and resources through the UI, and custom MCP resource types. Use this skill when requests mention Orchard Core MCP Server, Configure an MCP Server, Feature Overview, Enable the MCP Server Feature, Supported MCP Capabilities, Authentication Modes, or closely related Orchard Core implementation, setup, extension, or troubleshooting work. Strong matches include work with CrestApps.OrchardCore.AI.Mcp.Server, CrestApps.OrchardCore.AI, DatabaseResourceTypeHandler, IReadOnlyDictionary, ListPrompts, GetPrompt, ListResources, ReadResource, ListResourceTemplates, OpenId, ApiKey, RequireAccessPermission. It also helps with Supported MCP Capabilities, Authentication Modes, OpenId Configuration, plus the code patterns, admin flows, recipe steps, and referenced examples captured in this skill.

- Skill: `crestapps/orchardcore-ai-mcp-server` (Agent Skill)
- Install (CLI): `npx skillmds@latest add crestapps/orchardcore-ai-mcp-server`
- Raw SKILL.md: https://api.skillmd.com/api/skills/crestapps/orchardcore-ai-mcp-server/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: Apache-2.0
- Author: CrestApps (https://skillmd.com/u/crestapps)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/crestapps/orchardcore-ai-mcp-server

---


# Orchard Core MCP Server - Prompt Templates

## Configure an MCP Server

You are an Orchard Core expert. Generate configuration and admin guidance for exposing Orchard Core AI capabilities through the CrestApps MCP Server feature.

### Guidelines
- Use feature ID `CrestApps.OrchardCore.AI.Mcp.Server`.
- The MCP server exposes Orchard AI tools, MCP prompts, MCP resources, and templated resources.
- The server uses the MCP Streamable HTTP transport at `/mcp`.
- The server feature depends on `CrestApps.OrchardCore.AI`; add other features such as AI Agent only when their tools are intended to be exposed.
- Prefer authenticated access in production.
- Prompts and resources can be managed from the admin UI.
- Resource URIs are auto-constructed by the system from `{source}://{itemId}/{path}`.

### Feature Overview

| Feature | Feature ID | Description |
|---------|-----------|-------------|
| MCP Server | `CrestApps.OrchardCore.AI.Mcp.Server` | Expose Orchard Core as an MCP-compatible server |

### Enable the MCP Server Feature

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

### Supported MCP Capabilities

| Capability | Description |
|------------|-------------|
| Tools | Exposes registered Orchard AI tools as MCP tools |
| Prompts | Exposes MCP prompts through `ListPrompts` and `GetPrompt` |
| Resources | Exposes static resources through `ListResources` and `ReadResource` |
| Templated Resources | Exposes variable-based resource templates through `ListResourceTemplates` |

### Expose Documentation Search as a Tool

Use an AI Tool Instance for documentation lookup instead of adding a
documentation-specific MCP prompt. Do not point the built-in
`http-api-request` source directly at the static search indexes published by
the Orchard Core and CrestApps documentation sites. They use large
client-side indexes, ignore query parameters, and the source has no response
filtering or size limit. The Orchard Core Gallery is a package and module
discovery site, not a documentation search API.

Enable `CrestApps.OrchardCore.AI.ToolInstances` and use either:

- An `http-api-request` instance targeting a search service that you own and
  populate from the documentation and gallery data.
- A custom tool instance source that fetches and caches the static indexes
  server-side and returns only matching entries.

The indexed source data may include:

- `https://docs.orchardcore.net`
- `https://core.crestapps.com`
- `https://orchardcore.crestapps.com`
- `https://gallery.orchardcore.net` for package and module discovery

Use `GET` only, set `AllowModelProvidedBody = false`, leave credentials empty
for public sources, set a short timeout, and give each instance a precise
description. Keep these instances separate from privileged management or
content tools, and protect access with the generated
`AccessAITool_{functionName}` permission.

### Authentication Modes

| Mode | Description | Recommended Use |
|------|-------------|-----------------|
| `OpenId` | Uses OpenID Connect via the API scheme | Production |
| `ApiKey` | Uses a configured API key | Simple server-to-server integrations |
| `None` | No authentication | Local development only |

### OpenId Configuration

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

When `RequireAccessPermission` is `true`, callers must have the `AccessMcpServer` permission.

### ApiKey Configuration

```json
{
  "OrchardCore": {
    "CrestApps": {
      "AI": {
        "McpServer": {
          "AuthenticationType": "ApiKey",
          "ApiKey": "{{McpServerApiKey}}"
        }
      }
    }
  }
}
```

Accepted `Authorization` header formats include:

- `Bearer <key>`
- `ApiKey <key>`
- raw key value

### Development-Only Configuration

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

### Server Endpoint

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

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/mcp` | `POST` (and `GET`/`DELETE`) | Streamable HTTP transport endpoint (current MCP standard) |

### Add MCP Prompts via Admin UI

1. Navigate to **Artificial Intelligence → MCP Prompts**.
2. Click **Add Prompt**.
3. Fill in:
   - **Name**: The unique MCP prompt identifier.
   - **Display Text**: Friendly admin name.
   - **Description**: Optional description for clients.
4. Add one or more **Messages**.
   - Each message includes a **Role** such as `system` or `user`.
   - Each message includes **Content**.
5. Save the prompt.

Clients can discover prompts with `ListPrompts` and fetch their messages with `GetPrompt`.

### Add MCP Resources via Admin UI

1. Navigate to **Artificial Intelligence → MCP Resources**.
2. Click **Add Resource**.
3. Choose a **Resource Type** such as File, Media, Content Item, Content Type, Recipe Schema, or Recipe Step Schema.
4. Fill in:
   - **Display Text**
   - **Path**
   - **Name**
   - **Title** (optional)
   - **Description** (optional)
   - **MIME Type**
5. Save the resource.

### Resource Path Rules

- You only enter the **path** portion in the UI.
- The full URI is generated automatically as `{source}://{itemId}/{path}`.
- Templated resources can use variables such as `{fileName}`, `{contentType}`, or `{stepName}` depending on the resource type.

### Built-In Resource Types

| Type | Supported Variables | Description |
|------|---------------------|-------------|
| `file` | `{providerName}`, `{fileName}` | File provider access |
| `media` | `{path}` | Orchard media library |
| `content-item` | `{contentItemId}`, `{contentItemVersionId}` | Specific content item |
| `content-type` | `{contentType}` | Published items by content type |
| `recipe-schema` | none | Full JSON schema for all recipe steps |
| `recipe-step-schema` | `{stepName}` | JSON schema for one recipe step |
| `recipe` | `{recipeName}` | Recipe content by name |
| `ftp` | `{path}` | FTP or FTPS resource access |
| `sftp` | `{path}` | SFTP resource access |

### Recipe Example for MCP Resources

```json
{
  "steps": [
    {
      "name": "McpResource",
      "Resources": [
        {
          "Source": "file",
          "DisplayText": "Configuration File",
          "Resource": {
            "Uri": "file://configs/{providerName}/{fileName}",
            "Name": "config-file",
            "Description": "Application configuration",
            "MimeType": "application/json"
          }
        }
      ]
    }
  ]
}
```

### Register a Custom Resource Type

```csharp
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."] },
    ];
});
```

```csharp
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 your data source here.
        return Task.FromResult(CreateErrorResult(resource.Resource.Uri, "Not implemented."));
    }
}
```

### External Client Connection Example

Streamable HTTP transport connects to the `/mcp` base endpoint. The current host does not enable the SDK's optional legacy SSE endpoints.

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

### Security Best Practices

- Use `OpenId` in production whenever possible.
- Store API keys in environment variables or secrets.
- Grant `AccessMcpServer` only to trusted identities.
- Remember that exposed tools still respect Orchard Core permissions.
- Keep tenant isolation in mind; MCP operates in a tenant context.