googleapis/mcp-toolbox · error

MCP Auth is enabled but Toolbox URL is missing. Please provi

Error message

MCP Auth is enabled but Toolbox URL is missing. Please provide it via --toolbox-url flag or TOOLBOX_URL environment variable

What it means

When MCP auth is enabled, the toolbox must know the public URL of the toolbox server (ToolboxUrl) for auth redirects/metadata. The value may come from --toolbox-url or the TOOLBOX_URL env var; if both are empty after the env fallback, run() returns this error and the server never starts.

Source

Thrown at cmd/root.go:458

	var mcpAuthEnabled bool
	for _, authSvc := range opts.Cfg.AuthServiceConfigs {
		if authSvc.IsMCPEnabled() {
			mcpAuthEnabled = true
			break
		}
	}

	if mcpAuthEnabled {
		if opts.Cfg.EnableAPI {
			errMsg := fmt.Errorf("MCP Auth cannot be enabled together with the legacy HTTP API (--enable-api)")
			opts.Logger.ErrorContext(ctx, errMsg.Error())
			return errMsg
		}
		if opts.Cfg.ToolboxUrl == "" {
			opts.Cfg.ToolboxUrl = os.Getenv("TOOLBOX_URL")
		}
		if opts.Cfg.ToolboxUrl == "" {
			errMsg := fmt.Errorf("MCP Auth is enabled but Toolbox URL is missing. Please provide it via --toolbox-url flag or TOOLBOX_URL environment variable")
			opts.Logger.ErrorContext(ctx, errMsg.Error())
			return errMsg
		}
	}

	// start server
	s, err := server.NewServer(ctx, opts.Cfg)
	if err != nil {
		errMsg := fmt.Errorf("toolbox failed to initialize: %w", err)
		opts.Logger.ErrorContext(ctx, errMsg.Error())
		return errMsg
	}

	useTLS := opts.Cfg.CertFile != "" || opts.Cfg.KeyFile != ""
	protocol := "http"
	if useTLS {
		protocol = "https"
	}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Pass --toolbox-url https://your-public-host to the toolbox command
2. Set the TOOLBOX_URL environment variable (e.g. export TOOLBOX_URL=https://your-public-host)
3. Check the env var name/spelling in your shell or container environment

Example fix

// before
./toolbox --mcp-auth ...
// after
TOOLBOX_URL=https://toolbox.example.com ./toolbox --mcp-auth ...

# fail fast before starting toolbox
: "${TOOLBOX_URL:?must set --toolbox-url or TOOLBOX_URL when MCP auth is enabled}"
[[ "$TOOLBOX_URL" == https://* ]] || echo "warning: TOOLBOX_URL should be a public https URL"

When it happens

Trigger: mcpAuthEnabled=true and neither opts.Cfg.ToolboxUrl (via --toolbox-url) nor the TOOLBOX_URL environment variable is set.

Common situations: Deploying behind a proxy/ingress where the external URL differs from the bind address and the operator forgot the flag; CI containers where TOOLBOX_URL is not exported; typos like TOOLBOXURL.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• MCP Auth cannot be enabled together with the legacy HTTP API
• failed to check auth requirements: %w
• `introspectionEndpoint` is not allowed when `mcpEnabled` is
• `introspectionMethod` is not allowed when `mcpEnabled` is fa
• `introspectionParamName` is not allowed when `mcpEnabled` is

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/456afb2a0c743ce9. Report an issue: GitHub.