mcp-patterns

MCP Development Patterns

This skill loads comprehensive patterns for building MCP tools using the @umbraco-cms/mcp-server-sdk.

When to Use

Use this skill when:

• Starting to create new MCP tools
• Needing a reference for tool patterns
• Understanding how to use the toolkit helpers
• Setting up a new MCP server project

Core Architecture

Tool Definition Pattern

All tools follow this structure:

import {
  withStandardDecorators,
  executeGetApiCall,
  executeVoidApiCall,
  createToolResult,
  CAPTURE_RAW_HTTP_RESPONSE,
  ToolDefinition,
} from "@umbraco-cms/mcp-server-sdk";

const MyTool = {
  name: "tool-name",
  description: "What the tool does",
  inputSchema: zodSchema.shape,
  outputSchema: responseSchema,  // For GET operations
  slices: ["read"],              // Categorization
  annotations: {
    readOnlyHint: true,          // For GET
    destructiveHint: true,       // For DELETE
    idempotentHint: true,        // For PUT
  },
  handler: async (params) => {
    // Implementation
  },
} satisfies ToolDefinition<...>;

export default withStandardDecorators(MyTool);

API Client Configuration

Configure once at server startup:

import { configureApiClient } from "@umbraco-cms/mcp-server-sdk";
import { getMyAPI } from "./api/generated/myApi.js";

configureApiClient(() => getMyAPI());

Helper Functions

executeGetApiCall

For GET operations that return data:

return executeGetApiCall<ReturnType<Client["method"]>, Client>(
  (client) => client.method(params, CAPTURE_RAW_HTTP_RESPONSE)
);

executeVoidApiCall

For DELETE/PUT operations that return void:

return executeVoidApiCall<Client>(
  (client) => client.deleteItem(id, CAPTURE_RAW_HTTP_RESPONSE)
);

createToolResult / createToolResultError

For custom responses (typically CREATE operations):

if (response.status === 201) {
  return createToolResult({ success: true, id: extractedId });
} else {
  return createToolResultError(response.data);
}