MCP Extension Best Practices

Follow these guidelines when building MCP extension tools.

Tool Naming

Use lowercase names with underscores, prefixed by feature area:

• blog_post_list -- good
• ecommerce_product_search -- good
• analytics_report_generate -- good
• BlogPostList -- avoid camelCase
• post_list -- avoid missing feature prefix, may conflict with other extensions

JSON Input Schema

The inputSchemaJson field must be a valid JSON object. Follow these conventions:

• Root "type" must be "object"
• Define each parameter in "properties" with a "type" and "description"
• List mandatory parameters in a "required" array
• Write descriptions that help Claude understand when and how to use each parameter

{
  "type": "object",
  "properties": {
    "postId": {
      "type": "integer",
      "description": "ID of the blog post to retrieve"
    },
    "includeContent": {
      "type": "boolean",
      "description": "Include full post content in response (default true)"
    }
  },
  "required": ["postId"]
}

Parameter Validation

Check required parameters early and return clear error messages:

int postId = McpResponseHelper.GetIntArg(args, "postId");
if (postId == 0) {
    return McpResponseHelper.Error(cp, "postId is required");
}

Error Handling

Wrap tool logic in try-catch blocks and always report errors:

try {
    // Tool logic
    return McpResponseHelper.Success(cp, result);
} catch (Exception ex) {
    cp.Site.ErrorReport(ex);
    return McpResponseHelper.Error(cp, "Error listing blog posts");
}

Never let exceptions propagate unhandled. The MCP Server will catch them, but the error message will be generic.

GUIDs

Generate unique GUIDs for your collection, addon, and each tool definition record. Never reuse GUIDs from documentation examples. Use Visual Studio (Tools > Create GUID) or an online GUID generator.

Tool Descriptions

Write descriptions that help Claude decide when to use each tool. Include:

• What the tool does
• What data it returns
• Any important constraints or defaults

Good: "List blog posts with optional filters for status (draft, published, archived) and author. Returns title, slug, status, author, and publish date for each post."

Weak: "Lists posts."

Caching Behavior

Extension tool definitions are cached by the MCP Server for 5 minutes. During development:

• After modifying tool definitions in the database, changes may not appear for up to 5 minutes
• Restart the application pool to clear the cache immediately
• Once installed via collection XML, definitions load on the next cache refresh

Testing

1. Install your collection on a Contensive site that has aoMCP installed
2. Wait 5 minutes or restart the app pool to refresh the tool cache
3. Call tools/list and verify your tools appear
4. Call each tool individually and verify responses
5. Test undo by creating or updating content, then calling undo_list and undo_apply
6. Check the Contensive error log for any unreported exceptions