fix(plugins): discover MCP servers from mcp.json at plugin root

.github/skills/create-canvas-extension/SKILL.md

@@ -72,7 +72,7 @@ Create `plugins/<extension-id>/plugin.json` with this shape:
 }
 ```
 
-Keep Agent Plugins fields at the manifest top level. Repository composition belongs only under `extensions.com.github.awesome-copilot`; do not put `agents`, `commands`, `hooks`, `mcpServers`, or `skills` at the top level or directly under `extensions`. Do not add `x-awesome-copilot`, `standalone`, or other repository-specific top-level fields.
+Keep Agent Plugins fields at the manifest top level. Repository composition belongs only under `extensions.com.github.awesome-copilot`; do not put `agents`, `commands`, `hooks`, or `skills` at the top level or directly under `extensions`. MCP servers are declared in `mcp.json` at the plugin root, never in `plugin.json`. Do not add `x-awesome-copilot`, `standalone`, or other repository-specific top-level fields.
 
 For an existing parent plugin, create or update:
 

.github/workflows/validate-plugins.yml

@@ -52,7 +52,8 @@ jobs:
               'All internal plugins and extensions must include:',
               '- `"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json"` in `plugin.json`',
               '- A valid `name`, `description`, and `version`',
-              '- Repository composition (`agents`, `commands`, `hooks`, `mcpServers`, `skills`, and reusable `extensions`) under `extensions.com.github.awesome-copilot`',
+              '- Repository composition (`agents`, `commands`, `hooks`, `skills`, and reusable `extensions`) under `extensions.com.github.awesome-copilot`',
+              '- MCP servers declared in `mcp.json` at the plugin root, not in `plugin.json`',
               '- For **extensions**: `extensions.com.github.copilot.logo` must be set to `"assets/preview.png"`',
               '',
               'Do not put repository composition fields at the manifest top level or directly under `extensions`; they must be nested under `extensions.com.github.awesome-copilot`.',

AGENTS.md

@@ -121,6 +121,7 @@ All agent files (`*.agent.md`) and instruction files (`*.instructions.md`) must
 - plugin.json must have `description` field (describing the plugin's purpose)
 - plugin.json must have `version` field (semantic version, e.g., "1.0.0")
 - Plugin content is defined declaratively in plugin.json under `extensions.com.github.awesome-copilot` using source-only composition fields (`agents`, `hooks`, `skills`, and `extensions`). Source files live in top-level directories and are materialized into plugins by CI. This namespace is stripped from the served manifest — skills use the standard `skills/` directory and Copilot-specific content uses `com.github.copilot/`.
+- MCP servers are **not** a composition field. Per the Agent Plugins spec they are declared in an `mcp.json` file at the plugin root, which is committed alongside `plugin.json` and shipped as-is. Do not add `mcpServers` to `plugin.json`, and do not use the legacy `.mcp.json` filename.
 - The `marketplace.json` file is automatically generated from all plugins during build
 - Plugins are discoverable and installable via GitHub Copilot CLI
 
@@ -331,6 +332,7 @@ For plugins (plugins/\*/):
 - [ ] Directory name is lower case with hyphens
 - [ ] If `keywords` is present, it is an array of lowercase hyphenated strings
 - [ ] If composition arrays are present under `extensions.com.github.awesome-copilot`, each entry is a valid relative path
+- [ ] If the plugin ships MCP servers, they are declared in `mcp.json` at the plugin root (with the `mcp.schema.json` `$schema`), not in `plugin.json` or `.mcp.json`
 - [ ] The plugin does not reference non-existent files
 - [ ] Run `npm run plugin:validate` and `npm run build` to verify the plugin passes all checks
 

eng/agent-plugin-schema.mjs

@@ -1,4 +1,6 @@
 import Ajv2020 from "ajv/dist/2020.js";
+import fs from "node:fs";
+import path from "node:path";
 
 export const AGENT_PLUGIN_SCHEMA_URL = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
 export const AGENT_PLUGIN_SCHEMA = {
@@ -23,3 +25,309 @@ export function validateAgentPluginManifest(manifest) {
   return validate(manifest) ? [] : (validate.errors ?? []).map((error) =>
     `${error.instancePath || "manifest"} ${error.message}`);
 }
+
+export const AGENT_PLUGIN_MCP_SCHEMA_URL = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
+export const AGENT_PLUGIN_MCP_SCHEMA = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: AGENT_PLUGIN_MCP_SCHEMA_URL,
+  title: "Agent Plugins MCP Configuration",
+  type: "object",
+  properties: {
+    $schema: { const: AGENT_PLUGIN_MCP_SCHEMA_URL },
+    mcpServers: { type: "object", additionalProperties: { $ref: "#/$defs/server" } },
+  },
+  required: ["$schema", "mcpServers"],
+  additionalProperties: false,
+  $defs: {
+    server: {
+      title: "MCP server",
+      oneOf: [
+        { $ref: "#/$defs/stdioServer" },
+        { $ref: "#/$defs/streamableHttpServer" },
+        { $ref: "#/$defs/sseServer" },
+      ],
+    },
+    stdioServer: {
+      title: "stdio MCP server",
+      type: "object",
+      properties: {
+        type: { const: "stdio" },
+        command: { type: "string", minLength: 1 },
+        args: { type: "array", items: { type: "string" } },
+        env: {
+          type: "object",
+          propertyNames: { not: { enum: ["PLUGIN_ROOT", "PLUGIN_DATA"] } },
+          additionalProperties: { type: "string" },
+        },
+        cwd: {
+          type: "string",
+          pattern: "^(?:\\./|\\$\\{PLUGIN_ROOT\\}(?:/|$)|\\$\\{PLUGIN_DATA\\}(?:/|$))",
+        },
+      },
+      required: ["type", "command"],
+      additionalProperties: false,
+    },
+    streamableHttpServer: {
+      title: "Streamable HTTP MCP server",
+      type: "object",
+      properties: {
+        type: { const: "streamable-http" },
+        url: { type: "string", minLength: 1 },
+        headers: { $ref: "#/$defs/headers" },
+      },
+      required: ["type", "url"],
+      additionalProperties: false,
+    },
+    sseServer: {
+      title: "Legacy HTTP+SSE MCP server",
+      type: "object",
+      properties: {
+        type: { const: "sse" },
+        url: { type: "string", minLength: 1 },
+        headers: { $ref: "#/$defs/headers" },
+      },
+      required: ["type", "url"],
+      additionalProperties: false,
+    },
+    headers: { title: "HTTP headers", type: "object", additionalProperties: { type: "string" } },
+  },
+};
+
+const mcpAjv = new Ajv2020({ allErrors: true });
+const validateMcp = mcpAjv.compile(AGENT_PLUGIN_MCP_SCHEMA);
+
+// A bare oneOf failure reports every branch at once, so errors for a server whose
+// `type` is a known discriminator are re-derived from that branch alone.
+const MCP_SERVER_BRANCHES = {
+  stdio: "stdioServer",
+  "streamable-http": "streamableHttpServer",
+  sse: "sseServer",
+};
+const MCP_SERVER_TYPES = Object.keys(MCP_SERVER_BRANCHES);
+
+function isBareExecutableOrRelativePath(command) {
+  if (typeof command !== "string" || command.length === 0) {
+    return false;
+  }
+  if (command.startsWith("./")) {
+    return true;
+  }
+  return !command.includes("/") && !command.includes("\\");
+}
+
+function isPathWithinRoot(root, value) {
+  const normalizedValue = value.replaceAll("\\", path.sep).replaceAll("/", path.sep).replace(/^[/\\]+/, "");
+  const candidate = path.resolve(root, normalizedValue);
+  const relative = path.relative(root, candidate);
+  if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    return false;
+  }
+
+  let rootRealPath;
+  try {
+    rootRealPath = fs.realpathSync.native(root);
+  } catch {
+    return false;
+  }
+  let existingPath = candidate;
+  const missingSegments = [];
+  while (true) {
+    let resolvedExistingPath;
+    try {
+      fs.lstatSync(existingPath);
+      resolvedExistingPath = fs.realpathSync.native(existingPath);
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        return false;
+      }
+      try {
+        fs.readlinkSync(existingPath);
+        return false;
+      } catch (readlinkError) {
+        if (readlinkError.code !== "EINVAL" && readlinkError.code !== "ENOENT") {
+          return false;
+        }
+      }
+      const parent = path.dirname(existingPath);
+      if (parent === existingPath) {
+        return false;
+      }
+      missingSegments.unshift(path.basename(existingPath));
+      existingPath = parent;
+      continue;
+    }
+    const resolvedCandidate = path.join(resolvedExistingPath, ...missingSegments);
+    const resolvedRelative = path.relative(rootRealPath, resolvedCandidate);
+    return resolvedRelative !== ".." &&
+      !resolvedRelative.startsWith(`..${path.sep}`) &&
+      !path.isAbsolute(resolvedRelative);
+  }
+}
+
+function isContainedRelativeCwd(cwd, pluginDir) {
+  if (typeof cwd !== "string" || cwd.length === 0) {
+    return false;
+  }
+  const placeholder = cwd.match(/^\$\{(PLUGIN_ROOT|PLUGIN_DATA)\}(\/.*)?$/);
+  if (placeholder) {
+    if (placeholder[1] === "PLUGIN_DATA") {
+      return isLexicallyWithinRoot(placeholder[2] ?? "");
+    }
+    return !pluginDir || isPathWithinRoot(pluginDir, placeholder[2] ?? "");
+  }
+  if (!cwd.startsWith("./")) {
+    return false;
+  }
+  return !pluginDir || isPathWithinRoot(pluginDir, cwd);
+}
+
+function isLexicallyWithinRoot(value) {
+  let depth = 0;
+  for (const segment of value.split(/[\\/]/)) {
+    if (!segment || segment === ".") continue;
+    if (segment === "..") {
+      if (depth === 0) return false;
+      depth--;
+    } else {
+      depth++;
+    }
+  }
+  return true;
+}
+
+function isLoopbackHostname(hostname) {
+  const normalized = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  return normalized === "localhost" || normalized === "::1" || /^127(?:\.\d{1,3}){3}$/.test(normalized);
+}
+
+// Headers in mcp.json are visible package data. These names unambiguously carry
+// credentials; API-key names are intentionally rejected even when their value is
+// a placeholder, so users configure them in their local MCP client instead.
+const CREDENTIAL_HEADER_NAMES = new Set([
+  "authorization",
+  "proxy-authorization",
+  "cookie",
+  "set-cookie",
+  "api-key",
+  "x-api-key",
+  "x-api-token",
+  "x-auth-token",
+  "x-access-token",
+  "access-token",
+]);
+
+function validateRemoteServer(server, name) {
+  const errors = [];
+  let parsedUrl;
+  try {
+    parsedUrl = new URL(server.url);
+  } catch {
+    errors.push(`/mcpServers/${name}/url must be an absolute HTTP(S) URL`);
+    return errors;
+  }
+  if (!/^https?:\/\//i.test(server.url) ||
+      parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:" ||
+      !parsedUrl.hostname || parsedUrl.username || parsedUrl.password || parsedUrl.hash) {
+    errors.push(`/mcpServers/${name}/url must be an absolute HTTP(S) URL without userinfo or fragment`);
+  } else if (parsedUrl.protocol === "http:" && !isLoopbackHostname(parsedUrl.hostname)) {
+    errors.push(`/mcpServers/${name}/url must use HTTPS for non-loopback hosts`);
+  }
+
+  if (server.headers !== undefined) {
+    const seen = new Set();
+    for (const [headerName, headerValue] of Object.entries(server.headers)) {
+      if (!/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(headerName)) {
+        errors.push(`/mcpServers/${name}/headers/${headerName} must be a valid HTTP header name`);
+      }
+      const normalizedName = headerName.toLowerCase();
+      if (CREDENTIAL_HEADER_NAMES.has(normalizedName)) {
+        errors.push(`/mcpServers/${name}/headers/${headerName} must not contain credentials or secrets`);
+      }
+      if (seen.has(normalizedName)) {
+        errors.push(`/mcpServers/${name}/headers must not contain duplicate header names`);
+      }
+      seen.add(normalizedName);
+      if (/[\u0000-\u0008\u000A-\u001F\u007F]/.test(headerValue)) {
+        errors.push(`/mcpServers/${name}/headers/${headerName} must be a valid HTTP header value`);
+      }
+    }
+  }
+  return errors;
+}
+
+function formatMcpError(error) {
+  const extra = error.params?.additionalProperty
+    ? ` (${error.params.additionalProperty})`
+    : "";
+  return `${error.instancePath || "config"} ${error.message}${extra}`;
+}
+
+export function validateAgentPluginMcpConfig(config, pluginDir) {
+  if (validateMcp(config)) {
+    const semanticErrors = [];
+    const servers = config?.mcpServers;
+    if (typeof servers === "object" && servers !== null && !Array.isArray(servers)) {
+      for (const [name, server] of Object.entries(servers)) {
+        if (typeof server !== "object" || server === null || Array.isArray(server)) {
+          continue;
+        }
+        if (server.type === "streamable-http" || server.type === "sse") {
+          semanticErrors.push(...validateRemoteServer(server, name));
+          continue;
+        }
+        if (server.type !== "stdio") {
+          continue;
+        }
+        const commandIsContained = !server.command.startsWith("./") ||
+          !pluginDir || isPathWithinRoot(pluginDir, server.command);
+        if (!isBareExecutableOrRelativePath(server.command) || !commandIsContained) {
+          semanticErrors.push(`/mcpServers/${name}/command must be a bare executable name or a plugin-relative path starting with "./"`);
+        }
+        if (server.cwd !== undefined && !isContainedRelativeCwd(server.cwd, pluginDir)) {
+          semanticErrors.push(`/mcpServers/${name}/cwd must stay within the plugin root or plugin data directory`);
+        }
+      }
+    }
+    return semanticErrors;
+  }
+  const rawErrors = validateMcp.errors ?? [];
+  const servers = config?.mcpServers;
+  const hasServerObject = typeof servers === "object" && servers !== null && !Array.isArray(servers);
+
+  const messages = [];
+  for (const error of rawErrors) {
+    if (hasServerObject && error.instancePath.startsWith("/mcpServers/")) {
+      continue;
+    }
+    messages.push(formatMcpError(error));
+  }
+
+  if (hasServerObject) {
+    for (const [name, server] of Object.entries(servers)) {
+      if (typeof server !== "object" || server === null || Array.isArray(server)) {
+        messages.push(`/mcpServers/${name} must be an object`);
+        continue;
+      }
+      const branch = MCP_SERVER_BRANCHES[server.type];
+      if (!branch) {
+        messages.push(`/mcpServers/${name}/type must be one of ${MCP_SERVER_TYPES.join(", ")}`);
+        continue;
+      }
+      const branchValidator = mcpAjv.getSchema(`${AGENT_PLUGIN_MCP_SCHEMA_URL}#/$defs/${branch}`);
+      if (branchValidator(server)) {
+        continue;
+      }
+      for (const error of branchValidator.errors ?? []) {
+        if (error.keyword === "not") {
+          continue;
+        }
+        const suffix = error.keyword === "propertyNames"
+          ? ` "${error.params?.propertyName}" is reserved`
+          : formatMcpError(error).slice(error.instancePath.length || "config".length);
+        messages.push(`/mcpServers/${name}${error.instancePath}${suffix}`);
+      }
+
+    }
+  }
+  return messages;
+}

eng/generate-website-data.mjs

@@ -591,30 +591,20 @@ function generatePluginsData(gitDates, resourceIndex = {}) {
         ];
       });
 
-      // Parse mcpServers: supports a path to a .mcp.json file or an inline object
+      // Discover MCP servers from the spec-mandated mcp.json at the plugin root.
       const mcpItems = [];
-      if (composition.mcpServers) {
-        let mcpServersObj = null;
-        let mcpConfigPath = relPath;
-        if (typeof composition.mcpServers === "string") {
-          const manifestMcpPath = composition.mcpServers.replace(/^\.\//, "");
-          mcpConfigPath = manifestMcpPath ? `${relPath}/${manifestMcpPath}` : relPath;
-          const mcpJsonPath = path.join(pluginDir, manifestMcpPath);
-          if (fs.existsSync(mcpJsonPath)) {
-            try {
-              const mcpJson = JSON.parse(fs.readFileSync(mcpJsonPath, "utf-8"));
-              mcpServersObj = mcpJson.mcpServers || mcpJson;
-            } catch {
-              // ignore parse errors
+      const mcpJsonPath = path.join(pluginDir, "mcp.json");
+      if (fs.existsSync(mcpJsonPath) && fs.statSync(mcpJsonPath).isFile()) {
+        try {
+          const mcpJson = JSON.parse(fs.readFileSync(mcpJsonPath, "utf-8"));
+          const mcpServers = mcpJson.mcpServers;
+          if (mcpServers && typeof mcpServers === "object") {
+            for (const serverName of Object.keys(mcpServers)) {
+              mcpItems.push({ kind: "mcp", path: `${relPath}/mcp.json`, title: serverName });
             }
           }
-        } else if (typeof composition.mcpServers === "object") {
-          mcpServersObj = composition.mcpServers;
-        }
-        if (mcpServersObj) {
-          for (const serverName of Object.keys(mcpServersObj)) {
-            mcpItems.push({ kind: "mcp", path: mcpConfigPath, title: serverName });
-          }
+        } catch {
+          // ignore parse errors
         }
       }