Official guidance of parsing stdio package to mcp.json

[formulahendry]

I am working on MCP Registry support in GitHub Copilot for JetBrains IDEs. We wonder whether there is an official guidance about how to parse stdio package to mcp.json?

Using Azure MCP Server as example. The package section would be like this:

// Pattern#1: no runtimeArguments
"packages": [
  {
    "registry_type": "npm",
    "registry_base_url": "https://registry.npmjs.org",
    "identifier": "@azure/mcp",
    "version": "0.6.0",
    "transport": {
      "type": "stdio"
    },
    "package_arguments": [
      {
        "type": "positional",
        "value": "server"
      },
      {
        "type": "positional",
        "value": "start"
      }
    ]
  }
]

The pasring result in mcp.json would be like below:

"azure/azure-mcp": {
  "type": "stdio",
  "command": "npx",
  "args": [
    "-y",
    "@azure/mcp@latest",
    "server",
    "start"
  ]
}

However, the usage of runtimeArguments is not quite clear. Publisher may have different pattern for the MCP server.

runtime_arguments with -y:

// Pattern#2: partial runtimeArguments
"packages": [
  {
    "registry_type": "npm",
    "registry_base_url": "https://registry.npmjs.org",
    "identifier": "@azure/mcp",
    "version": "0.6.0",
    "transport": {
      "type": "stdio"
    },
    "runtime_arguments": [
      {
        "is_required": true,
        "format": "string",
        "value": "-y",
        "type": "positional",
        "name": "-y",
        "value_hint": "noninteractive_mode"
      }
    ],
    "package_arguments": [
      {
        "type": "positional",
        "value": "server"
      },
      {
        "type": "positional",
        "value": "start"
      }
    ]
  }
]

runtime_arguments with -y + package_name@version:

// Pattern#3: full runtimeArguments
"packages": [
  {
    "registry_type": "npm",
    "registry_base_url": "https://registry.npmjs.org",
    "identifier": "@azure/mcp",
    "version": "0.6.0",
    "transport": {
      "type": "stdio"
    },
    "runtime_arguments": [
      {
        "is_required": true,
        "format": "string",
        "value": "-y",
        "type": "positional",
        "name": "-y",
        "value_hint": "noninteractive_mode"
      },
      {
        "type": "positional",
        "value": "@azure/[email protected]"
      }
    ],
    "package_arguments": [
      {
        "type": "positional",
        "value": "server"
      },
      {
        "type": "positional",
        "value": "start"
      }
    ]
  }
]

For the above 3 patterns, which one or ones are recommended? WIth the clear pattern, we clients of MCP Registry could do the correct pasring.

In addtion, some stdio mcp server (especially oci) may have complicated arguments:

"github": {
    "command": "docker",
    "args": [
        "run",
        "-i",
        "--rm",
        "--port",
        "3001",
        "--name",
        "xyz",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
    ]
}

How is the recommended package section in registry, and how is the parsing logic?

[yaonyan]

I'm also looking for the specification on how to connect, with the goal of automatically retrieving the MCP tool definition list.

In my opinion, based on #123 and #124 , Pattern 1 is recommended – clients should automatically infer npx -y from registry_type: "npm" rather than including it in runtime_arguments, keeping registry entries clean and delegating runtime-specific logic to client SDKs.

[tadasant]

In my opinion, based on https://github.com/modelcontextprotocol/registry/issues/123 and https://github.com/modelcontextprotocol/registry/issues/124 , Pattern 1 is recommended – clients should automatically infer npx -y from registry_type: "npm" rather than including it in runtime_arguments, keeping registry entries clean and delegating runtime-specific logic to client SDKs.

Yes, this is correct, that is the intent.

Publisher may have different pattern for the MCP server.

You're right, we need to do better with forcing publishers to adhere to our standards to make fully compliant server.json files. @BobDickinson has been starting to drive some great work in this direction.

My recommendation in the meantime: prioritize integrating with servers that are properly following the best practices. The others will catch up eventually as we add more guardrails.

So runtime_arguments with -y: and runtime_arguments with -y + package_name@version: are incorrect and we will plan to discourage those patterns.

Would appreciate and welcome any contributions you may have to help document the expected best practices here better.

with the goal of automatically retrieving the MCP tool definition list.

I wouldn't recommend this and I don't expect we will encourage this practice as an ecosystem: MCP tools are dynamic, auth-gated, etc, so there is no conceivable way you could reliably pull a static list of tools just by connecting to a server. That's only the case in this early premature state where most MCP servers are simple, not auth-gated, etc.

In addtion, some stdio mcp server (especially oci) may have complicated arguments:

There is a complex OCI example here; does that help?

[yaonyan]

That's only the case in this early premature state where most MCP servers are simple, not auth-gated, etc.

Yeah, I became aware of that while experimenting with the connection process. Thanks for the reminder. Remote servers are mostly impossible - only stdio servers without auth requirements (like desktop/filesystem servers) are feasible.

Our use-case is building an agentic-server composer where users pick and combine tools from multiple MCP servers; to make server discovery and selection easier on the web we want to surface each server’s available tools (yes, this only reliably works for simple, non-auth stdio servers today), and users can also manually specify tool names via the SDK.

[tadasant]

Our use-case is building an agentic-server composer where users pick and combine tools from multiple MCP servers; to make server discovery and selection easier on the web we want to surface each server’s available tools (yes, this only reliably works for simple, non-auth stdio servers today), and users can also manually specify tool names via the SDK.

Makes sense. We do have some (early) plans to add enumerations of (all possible) tools into server.json: https://github.com/modelcontextprotocol/registry/issues/82

Not actively being worked on by anyone, so if someone was keen to champion that work, it's of interest to the community

[yaonyan]

Our use-case is building an agentic-server composer where users pick and combine tools from multiple MCP servers; to make server discovery and selection easier on the web we want to surface each server’s available tools (yes, this only reliably works for simple, non-auth stdio servers today), and users can also manually specify tool names via the SDK.

Makes sense. We do have some (early) plans to add enumerations of (all possible) tools into server.json: #82

Not actively being worked on by anyone, so if someone was keen to champion that work, it's of interest to the community

Thank you, I will look into it