Custom MCP Server URL Support Implementation Plan

• Update getMCPServerConfigsFromManifest() to respect custom URLs when provided in ToolingManifest.json
• Update documentation/comments to reflect support for custom URLs in manifest
• Add tests to validate custom URL functionality
• Address code review feedback (remove unused variables, improve type safety)
• Run security checks (0 vulnerabilities found)
• Revert unnecessary optional url field change
• Improve test assertions to validate full URLs
• Add mcpServerUniqueName fallback logic
• Replace 'any' type with proper interface
• Fix test environment variable handling
• Add ESM support flag to test scripts
• Use cross-env for cross-platform compatibility
• Add test coverage for headers field

Implementation Complete

This PR adds support for custom MCP server URLs in the Node.js SDK, replicating the functionality from the .NET SDK PR #147.

Changes Made:

1. Modified McpToolServerConfigurationService.ts:
   • The getMCPServerConfigsFromManifest() method now checks for custom URLs in manifest entries before falling back to default URL building
   • Added support for mcpServerUniqueName as fallback when mcpServerName is not provided (matching .NET implementation)
   • Replaced any type with proper MCPServerManifestEntry interface for type safety
   • Added validation to throw error if neither name field is provided
   • Preserves custom headers from manifest entries
2. Added MCPServerManifestEntry interface in contracts.ts:
   • Properly types manifest entries with optional mcpServerName, mcpServerUniqueName, url, and headers fields
   • Separates the manifest entry type from the returned MCPServerConfig type for clarity
3. Enhanced documentation: Updated JSDoc comments with examples showing how to use custom URLs and the fallback behavior
4. Added comprehensive tests: Created 10 unit tests covering various scenarios including custom URLs, default URLs, mixed configs, edge cases, the mcpServerUniqueName fallback logic, error handling, and custom headers preservation. Tests validate full URLs using Utility.BuildMcpServerUrl() for precision.
5. Fixed test environment handling: Updated test to use the same pattern as other tests in the repository for managing process.env
6. Added ESM support: Updated test scripts to include NODE_OPTIONS=--experimental-vm-modules flag to properly handle ES module imports with .js extensions used by the @modelcontextprotocol/sdk package
7. Cross-platform compatibility: Added cross-env package and updated all test scripts to use it for setting NODE_OPTIONS, ensuring tests work correctly on Windows, macOS, and Linux

Usage:

Users can now specify custom MCP server URLs and headers in their ToolingManifest.json:

{
  "mcpServers": [
    {
      "mcpServerName": "customServer",
      "url": "http://localhost:3000/custom-mcp",
      "headers": {
        "Authorization": "Bearer token123",
        "X-Custom-Header": "custom-value"
      }
    },
    {
      "mcpServerName": "mcp_MailTools"
    },
    {
      "mcpServerUniqueName": "mcp_OneDriveServer"
    }
  ]
}

The server name is determined by using mcpServerName if present, otherwise falling back to mcpServerUniqueName. Custom headers can be specified and will be preserved.

Backward Compatibility:

The changes are fully backward compatible. If the url field is not provided, the URL is automatically constructed using the server name as before.

Testing:

All 241 tests pass across all platforms, including the 10 new tests for custom MCP URL functionality.

• Fixes Custom MCP server URLs are not supported in the SDK #128

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.