serverless/serverless · error · ServerlessError

MCP_API_GATEWAY_PLUGIN_NOT_FOUND

MCP_API_GATEWAY_PLUGIN_NOT_FOUND

Error message

MCP servers are exposed through an API Gateway REST API, but the API Gateway compiler plugin was not found. This is an internal error - please report it at https://github.com/serverless/serverless/issues.

What it means

Error "MCP servers are exposed through an API Gateway REST API, but the API Gateway compiler plugin was not found. This is an internal error - please report it at https://github.com/serverless/serverless/issues." thrown in serverless/serverless.

Source

Thrown at packages/serverless/lib/plugins/aws/mcp/index.js:133

        this.warnDeployFunctionSkipsEnvironment()
        await this.repointFunctions(this.options.function)
      },
      // The staged file outlives the artifact it went into, so it is cleaned up
      // per command run rather than per packaging event: `finalize` is the last
      // thing a successful run does and `error` the last thing a failed one does
      // (`../../../classes/plugin-manager.js`), which together cover `package`,
      // `deploy` and `deploy function` without one hook per command. A hard
      // crash still bypasses both - hence the deterministic staged name, which
      // the next run overwrites.
      finalize: () => this.unstageEntry(),
      error: () => this.unstageEntry(),
      'before:package:compileEvents': async () => {
        if (!this.validated) return
        const apiGatewayPlugin = this.serverless.pluginManager.plugins.find(
          (plugin) => typeof plugin.registerExternalHttpEvents === 'function',
        )
        if (!apiGatewayPlugin) {
          throw new ServerlessError(
            'MCP servers are exposed through an API Gateway REST API, but the API Gateway compiler plugin was not found. This is an internal error - please report it at https://github.com/serverless/serverless/issues.',
            'MCP_API_GATEWAY_PLUGIN_NOT_FOUND',
            { stack: false },
          )
        }
        // Built before anything is registered: this is the step that can
        // refuse a configuration (a value Velocity would rewrite), and a
        // refusal must not leave half a service's routes contributed.
        const { descriptors, sources } = buildDiscoveryDescriptors({
          servers: this.validated.servers,
          provider: this.serverless.service.provider,
          // The stage the REST API is deployed to, which is not the config
          // stage when `provider.apiGateway.stage` renames it. The deployment's
          // own `ServiceEndpoint` output is built from this same resolution
          // (`../package/compile/events/api-gateway/lib/deployment.js`), so a
          // document built from `getStage()` would advertise a URL that answers
          // nothing while the summary printed the one that works.
          stage: this.provider.getApiGatewayStage(),

View on GitHub (pinned to b9d7ea51c8)

Solutions

1. Report the issue at https://github.com/serverless/serverless/issues as this indicates a missing internal plugin.
2. Reinstall or upgrade the Serverless Framework in case the installation is corrupted.

When it happens

Trigger: Thrown at packages/serverless/lib/plugins/aws/mcp/index.js:133 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of serverless/serverless@b9d7ea51c8 (2026-08-13). Data as JSON: /api/errors/4a411666289068b6. Report an issue: GitHub.