{"record":{"id":"456afb2a0c743ce9","repo":"googleapis/mcp-toolbox","slug":"mcp-auth-is-enabled-but-toolbox-url-is-missing-pl","errorCode":null,"errorMessage":"MCP Auth is enabled but Toolbox URL is missing. Please provide it via --toolbox-url flag or TOOLBOX_URL environment variable","messagePattern":"MCP Auth is enabled but Toolbox URL is missing\\. Please provide it via --toolbox-url flag or TOOLBOX_URL environment variable","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/root.go","lineNumber":458,"sourceCode":"\tvar mcpAuthEnabled bool\n\tfor _, authSvc := range opts.Cfg.AuthServiceConfigs {\n\t\tif authSvc.IsMCPEnabled() {\n\t\t\tmcpAuthEnabled = true\n\t\t\tbreak\n\t\t}\n\t}\n\n\tif mcpAuthEnabled {\n\t\tif opts.Cfg.EnableAPI {\n\t\t\terrMsg := fmt.Errorf(\"MCP Auth cannot be enabled together with the legacy HTTP API (--enable-api)\")\n\t\t\topts.Logger.ErrorContext(ctx, errMsg.Error())\n\t\t\treturn errMsg\n\t\t}\n\t\tif opts.Cfg.ToolboxUrl == \"\" {\n\t\t\topts.Cfg.ToolboxUrl = os.Getenv(\"TOOLBOX_URL\")\n\t\t}\n\t\tif opts.Cfg.ToolboxUrl == \"\" {\n\t\t\terrMsg := fmt.Errorf(\"MCP Auth is enabled but Toolbox URL is missing. Please provide it via --toolbox-url flag or TOOLBOX_URL environment variable\")\n\t\t\topts.Logger.ErrorContext(ctx, errMsg.Error())\n\t\t\treturn errMsg\n\t\t}\n\t}\n\n\t// start server\n\ts, err := server.NewServer(ctx, opts.Cfg)\n\tif err != nil {\n\t\terrMsg := fmt.Errorf(\"toolbox failed to initialize: %w\", err)\n\t\topts.Logger.ErrorContext(ctx, errMsg.Error())\n\t\treturn errMsg\n\t}\n\n\tuseTLS := opts.Cfg.CertFile != \"\" || opts.Cfg.KeyFile != \"\"\n\tprotocol := \"http\"\n\tif useTLS {\n\t\tprotocol = \"https\"\n\t}","sourceCodeStart":440,"sourceCodeEnd":476,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/cmd/root.go#L440-L476","documentation":"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.","triggerScenarios":"mcpAuthEnabled=true and neither opts.Cfg.ToolboxUrl (via --toolbox-url) nor the TOOLBOX_URL environment variable is set.","commonSituations":"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.","solutions":["Pass --toolbox-url https://your-public-host to the toolbox command","Set the TOOLBOX_URL environment variable (e.g. export TOOLBOX_URL=https://your-public-host)","Check the env var name/spelling in your shell or container environment"],"exampleFix":"// before\n./toolbox --mcp-auth ...\n// after\nTOOLBOX_URL=https://toolbox.example.com ./toolbox --mcp-auth ...","handlingStrategy":"validation","validationCode":"# fail fast before starting toolbox\n: \"${TOOLBOX_URL:?must set --toolbox-url or TOOLBOX_URL when MCP auth is enabled}\"\n[[ \"$TOOLBOX_URL\" == https://* ]] || echo \"warning: TOOLBOX_URL should be a public https URL\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always export TOOLBOX_URL in container/CI environments using MCP auth","Pass --toolbox-url explicitly in systemd units and compose files","Validate the URL is externally reachable, not just the bind address"],"tags":["configuration","mcp","auth","env-var"],"backgroundTag":"missing-required-config","analyzedSha":"8cc6e09de2ad7b8bffc77751799585a1401a48eb","analyzedAt":"2026-09-05T01:10:36.887Z","contentChangedAt":"2026-09-05T01:10:36.887Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}