feat: Add template variable support for remote transport URLs

[tadasant]

[Draft built largely with iterating with Claude Code; intended as a proof of concept, including this PR description, will clean up and review line by line later]

Summary

This PR adds template variable support for remote transport URLs, enabling multi-tenant deployments with configurable endpoints while maintaining full backwards compatibility.

Proper design - Uses clean LocalTransport and RemoteTransport separation with proper inheritance/composition.

Problem

The current schema promises URL templating with {curly_braces} for StreamableHttpTransport but provides no mechanism for Remote contexts to define what those variables should resolve to. This makes the feature unusable for remote servers.

Referenced issue: #394

• Users need multi-tenant remote servers with different endpoints per deployment
• Each tenant/region has its own URL (e.g., us-cell1.example.com, emea-cell1.example.com)
• Current schema doesn't support parameterized remote URLs

Solution

Clean separation with proper inheritance:

• LocalTransport: StdioTransport | StreamableHttpTransport | SseTransport

  • Used in Package context (non-breaking rename of existing behavior)
  • Variables in {curly_braces} reference parent arguments/environment variables

• RemoteTransport: (StreamableHttpTransport | SseTransport) + variables

  • Extends base transports via allOf composition - no duplication!
  • Adds variables object for URL templating
  • Only supports streamable-http and sse (stdio not valid for remotes)

Key Changes

Schema Updates

• LocalTransport: Clean union of existing three transport types for Package context
• RemoteTransport: Extends StreamableHttp/Sse with variables via allOf composition
• Package: Now uses LocalTransport reference (cleaner, non-breaking)
• Remotes: Uses RemoteTransport with proper inheritance

Go Types

• Keep base Transport struct unchanged for Package context
• RemoteTransport struct handles both cases with Variables field
• No code duplication - schemas properly reused

Variable Definition

The Remote context extends base transports cleanly:

{
  "type": "streamable-http", 
  "url": "https://api.example.github.io/mcp/{tenant_id}",
  "headers": [...],  // inherited from StreamableHttpTransport
  "variables": {     // added by RemoteTransport
    "tenant_id": {
      "description": "Tenant identifier", 
      "isRequired": true,
      "choices": ["us-cell1", "emea-cell1"]
    }
  }
}

Benefits

• No breaking changes: Package functionality completely unchanged, just renamed for clarity
• Proper inheritance: RemoteTransport extends base transports, no duplication
• Type safety: RemoteTransport can't use stdio (enforced at schema level)
• DRY design: Reuses StreamableHttp/Sse definitions via composition
• Clear separation: LocalTransport vs RemoteTransport naming
• Rich variables: Full Input capabilities (description, choices, isRequired, isSecret, default, format)

Test Plan

• Validate schema changes against existing examples - all pass
• Test backwards compatibility with existing server.json files - unchanged
• Verify new templating example validates correctly
• All lint/validation checks pass
• Schema inheritance works correctly
• Test with real multi-tenant deployment scenario

Architecture

Perfect separation with inheritance:

• Package + LocalTransport: {port} references --port argument or PORT env var from parent Package
• Remote + RemoteTransport: {tenant_id} references variables.tenant_id object, inherits all base transport properties
• Code reuse: StreamableHttp/Sse definitions shared via allOf, not duplicated

🤖 Generated with Claude Code

[connor4312]

The idea with the references initially here is that a server that is launched with stdio and has, for example, a --port argument could automatically reference the value of that argument in the transport. I hypothesize the vast majority of locally-launched servers are going to have an address detereministic from their command line inputs and (from a client PoV) asking the user to fill in the port in the url separately from a port in the package_arguments is just confusing.

[connor4312]

Also,

All existing server.json files remain valid

this is not the case -- this change is breaking for any packages that were already published with the original reference behavior (not sure if there are any, this was only in a recent addition)

[tadasant]

Ah, right. Thanks for the reminder that was the original reason we didn't include a separate field here.

The learning we've had since is that this doesn't work for the usage of StreamableHttpTransport and SseTransport within Remote.

Will think more on how we can properly combine (or separate out) the use cases.

[connor4312]

definitely -- I suggest perhaps combining the variables with an allOf in just the Remote case and adding some description in the property.

[tadasant]

Also re -

this is not the case -- this change is breaking for any packages that were already published with the original reference behavior (not sure if there are any, this was only in a recent addition)

That's my bad - I had forgotten this original use case inside Package and thus thought the reference to arguments/envvars was just a typo. This is all clearer now that you've reminded me :) Thanks again

[tadasant]

Feeling pretty good about the direction now: https://github.com/modelcontextprotocol/registry/pull/570/files

Not ready to land this, but intent for me here was to explore whether we can add this functionality without breaking changes. I think the answer is yes, so might punt this for a few days.

[BobDickinson]

I somehow missed this PR and created #576 (which should get closed if this PR is adopted). FWIW, I've reviewed this PR and am a fan of the approach (including adding variables to the remote transports for URI substitution).

[domdomegg]

I'm happy with this approach 👍. Might just need a rebase and minor code cleanup

[BobDickinson]

OK, I really like this PR and don't want to slow it down. That being said, in going through existing registry entries with an eye toward making them take full advantage of the configuration support offered, I ran across a case that might impact this.

The general use case for this feature is configurable ports for the package transport url (so we configure the port we want the server to run on, and then have the transport config pick up that same port from the runtime config). But what about the case where the port is not an argument or env var, but is another part of the config? For example (from a published server):

Current

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-16/server.schema.json",
  "name": "io.github.SamYuan1990/i18n-agent-action",
  "description": "An i18n github action for language translate",
  "version": "mcp",
  "packages": [
    {
      "registryType": "oci",
      "registryBaseUrl": "https://ghcr.io",
      "identifier": "SamYuan1990/i18n-agent-action",
      "version": "mcp",
      "runtimeHint": "docker",
      "transport": {
        "type": "sse",
        "url": "https://example.com:8080/sse"
      },
      "runtimeArguments": [
        {
          "description": "Port mapping from host to container",
          "value": "8080:8080",
          "type": "named",
          "name": "-p"
        }
      ]
    }
  ]
}

If we wanted to parameterize the port so we can change it and have it be reflected in the docker command and the transport url, we would do something like this:

Parameterized

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-16/server.schema.json",
  "name": "io.github.SamYuan1990/i18n-agent-action",
  "description": "An i18n github action for language translate",
  "version": "mcp",
  "packages": [
    {
      "registryType": "oci",
      "registryBaseUrl": "https://ghcr.io",
      "identifier": "SamYuan1990/i18n-agent-action",
      "version": "mcp",
      "runtimeHint": "docker",
      "transport": {
        "type": "sse",
        "url": "https://example.com:{host_port}/sse"
      },
      "runtimeArguments": [
        {
          "description": "Port mapping from host to container",
          "value": "{host_port}:8080",
          "type": "named",
          "name": "-p",
          "variables": {
            "host_port": {
              "description": "The host (local) port",
              "isRequired": true,
              "format": "number",
              "default": "8080"
            }
          }
        }
      ]
    }
  ]
}

For docker we have to parameterize (templatize) the port (-p) argument with a variable to make the host port configurable. With the current resolution logic, there would be no way to map the token in the url to that (because there is no corresponding arg or env var representing just the host port).

I would argue that the mapping logic is already a little "spicy" since you could theoretically have runtime args, package args, and env vars with conflicting names (so you already need to specify the resolution logic / priority for deterministic resolution). My recommendation is that the guidance for token substitution be amended to say that after checking the runtime args, package args, and env vars (in that order) that you then fall back to checking for a matching variable under each of those things (in the same order). That would support the exact case above and keep the syntax clean.

I also considered a syntax like {p.host_port} indicating look in the first matching config element (arg/env) named "p", then use it's variable called "host_port". It's more specific, but I'm not sure that's worth the complexity for what it solves (directing to a specific variable when there might be multiple config elements with the same variable name - and since the variable names are only internal and are under the publisher's control, it's their own fault if they're ambiguous IMO).

[connor4312]

Good callout.

I also considered a syntax like {p.host_port} indicating look in the first matching config element (arg/env) named "p", then use it's variable called "host_port".

I think I'd prefer this to the blind sub-variable matching. Though it would actually be {-p.host_port} in your example as -p is the name of the argument.

[BobDickinson]

I could certainly live with the directed (dot) references.

I can't explain exactly why, but {-p.host_port} and even {--port} hurt my eyes, even though they are technically correct. It's complicated by the fact that many publishers aren't using the -- in the argument name (even though the docs are very clear about it), making the tokens look prettier, but causing the generated args to be wrong. I have a lax mode of config generation that works around this (both in token matching and config generation), but I'm not happy about it. I have a validator proposal coming soon (with schema validation and a linter to catch logic errors / misconfigurations, including things like missing dashes in arg names).

But back to the point: I'd advocate that we specify that it's OK to omit the leading dashes for named arg matching in the url token just to make it not hurt my eyes, but maybe that's not a good enough reason ;)

[BobDickinson]

IMO, both StreamableHttpTransport and SseTransport url should have:

  "pattern": "^https?://[^\\s]+$"

So as to at least encourage url-like values (versus free form strings)

Currently StreamableHttpTransport has no pattern or format, and SseTransport has:

  "format": "uri"

which will prevent tokens in SSE (the intent to allow tokens in SSE seems clear, so I assume this is just an oversight).

[tadasant]

Sorry I've been slow to follow up here - planning to get into it tomorrow