Add custom MCP server URL support in Node.js SDK

[Copilot]

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.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Custom MCP server URLs are not supported in the SDK</issue_title>
<issue_description>Describe the bug
Custom MCP server URLs are not supported in the SDK.

Proposed solution:
This PR needs to be replicated for the Node.js SDK as well: microsoft/Agent365-dotnet#147
</issue_description>

Comments on the Issue (you are @copilot in this section)

• 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.

[Copilot]

Pull request overview

This PR adds support for custom MCP server URLs in the Node.js SDK, mirroring functionality from the .NET SDK. The implementation allows users to specify custom URLs in their ToolingManifest.json while maintaining backward compatibility with automatic URL construction.

Key Changes:

• Enhanced getMCPServerConfigsFromManifest() to respect custom URLs when provided in manifest entries
• Added MCPServerManifestEntry interface for proper typing of manifest entries, separating concerns from MCPServerConfig
• Implemented fallback logic to use mcpServerUniqueName when mcpServerName is not provided, matching .NET implementation

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
packages/agents-a365-tooling/src/McpToolServerConfigurationService.ts	Core implementation: checks for custom URLs in manifest before falling back to default URL building; adds name fallback logic and validation
packages/agents-a365-tooling/src/contracts.ts	Adds MCPServerManifestEntry interface to properly type manifest entries with optional fields
tests/tooling/McpToolServerConfigurationService.test.ts	Comprehensive test suite with 9 tests covering custom URLs, default URLs, mixed configs, edge cases, fallback logic, and error handling
tests/package.json	Adds NODE_OPTIONS flag to test scripts for ESM support needed by the MCP SDK package

[Copilot]

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated 3 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

[Copilot]

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated 2 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

[tmlsousa]

Should this be the other way around, i.e. use the unique name as default and if that does not exist then server name? Given that the unique name is usually used to construct the URL?
Actually, I'm wondering what is even the point of having a server name?

[pontemonti]

This is the current behavior in the .NET SDK and how we have been parsing the tooling manifest files previously. The idea was to just have one property since mcpServerName and mcpServerUniqueName are supposed to be the same thing - so we were getting rid of mcpServerUniqueName and just used mcpServerName. We can revisit the contract later.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.