stainless-api · dgellow · Feb 12, 2026 · Nov 30, 2025 · Dec 2, 2025 · Feb 12, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -245,23 +245,24 @@ When refactoring for better design:
 
 ```bash
 # Build everything
-make build
+./scripts/build
 
 # Format everything
-make format
+./scripts/format
 
 # Lint everything
-make lint
+./scripts/lint
 
 # Test mcp-front
+./scripts/test
 go test ./internal/... -v
 go test ./integration -v
 
 # Run mcp-front locally
 ./mcp-front -config config.json
 
 # Start docs dev server
-make doc
+./scripts/docs
 ```
 
 ## Documentation Site Guidelines

diff --git a/cmd/mcp-front/main.go b/cmd/mcp-front/main.go
@@ -22,27 +22,42 @@ func generateDefaultConfig(path string) error {
 			"addr":    ":8080",
 			"name":    "mcp-front",
 			"auth": map[string]any{
-				"kind":               "oauth",
-				"issuer":             "https://mcp.yourcompany.com",
-				"allowedDomains":     []string{"yourcompany.com"},
-				"allowedOrigins":     []string{"https://claude.ai"},
-				"tokenTtl":           "24h",
-				"storage":            "memory",
-				"googleClientId":     map[string]string{"$env": "GOOGLE_CLIENT_ID"},
-				"googleClientSecret": map[string]string{"$env": "GOOGLE_CLIENT_SECRET"},
-				"googleRedirectUri":  "https://mcp.yourcompany.com/oauth/callback",
-				"jwtSecret":          map[string]string{"$env": "JWT_SECRET"},
-				"encryptionKey":      map[string]string{"$env": "ENCRYPTION_KEY"},
+				"kind":           "oauth",
+				"issuer":         "https://mcp.yourcompany.com",
+				"allowedDomains": []string{"yourcompany.com"},
+				"allowedOrigins": []string{"https://claude.ai"},
+				"tokenTtl":       "24h",
+				"storage":        "memory",
+				"idp": map[string]any{
+					"provider":     "google",
+					"clientId":     map[string]string{"$env": "GOOGLE_CLIENT_ID"},
+					"clientSecret": map[string]string{"$env": "GOOGLE_CLIENT_SECRET"},
+					"redirectUri":  "https://mcp.yourcompany.com/oauth/callback",
+				},
+				"jwtSecret":     map[string]string{"$env": "JWT_SECRET"},
+				"encryptionKey": map[string]string{"$env": "ENCRYPTION_KEY"},
 			},
 		},
 		"mcpServers": map[string]any{
 			"postgres": map[string]any{
 				"transportType": "stdio",
 				"command":       "docker",
 				"args": []any{
-					"run", "--rm", "-i",
-					"mcp/postgres:latest",
-					map[string]string{"$env": "POSTGRES_URL"},
+					"run", "--rm", "-i", "--network", "host",
+					"-e", "POSTGRES_HOST",
+					"-e", "POSTGRES_PORT",
+					"-e", "POSTGRES_DATABASE",
+					"-e", "POSTGRES_USER",
+					"-e", "POSTGRES_PASSWORD",
+					"us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
+					"--stdio", "--prebuilt", "postgres",
+				},
+				"env": map[string]any{
+					"POSTGRES_HOST":     map[string]string{"$env": "POSTGRES_HOST"},
+					"POSTGRES_PORT":     map[string]string{"$env": "POSTGRES_PORT"},
+					"POSTGRES_DATABASE": map[string]string{"$env": "POSTGRES_DATABASE"},
+					"POSTGRES_USER":     map[string]string{"$env": "POSTGRES_USER"},
+					"POSTGRES_PASSWORD": map[string]string{"$env": "POSTGRES_PASSWORD"},
 				},
 			},
 		},

diff --git a/config-admin-example.json b/config-admin-example.json
@@ -7,13 +7,16 @@
     "auth": {
       "kind": "oauth",
       "issuer": "https://mcp.example.com",
+      "idp": {
+        "provider": "google",
+        "clientId": {"$env": "GOOGLE_CLIENT_ID"},
+        "clientSecret": {"$env": "GOOGLE_CLIENT_SECRET"},
+        "redirectUri": "https://mcp.example.com/oauth/callback"
+      },
       "allowedDomains": ["example.com"],
       "allowedOrigins": ["https://claude.ai"],
       "tokenTtl": "1h",
       "storage": "memory",
-      "googleClientId": {"$env": "GOOGLE_CLIENT_ID"},
-      "googleClientSecret": {"$env": "GOOGLE_CLIENT_SECRET"},
-      "googleRedirectUri": "https://mcp.example.com/oauth/callback",
       "jwtSecret": {"$env": "JWT_SECRET"},
       "encryptionKey": {"$env": "ENCRYPTION_KEY"}
     },

diff --git a/config-inline-example.json b/config-inline-example.json
@@ -7,13 +7,16 @@
     "auth": {
       "kind": "oauth",
       "issuer": "https://mcp.example.com",
+      "idp": {
+        "provider": "google",
+        "clientId": {"$env": "GOOGLE_CLIENT_ID"},
+        "clientSecret": {"$env": "GOOGLE_CLIENT_SECRET"},
+        "redirectUri": "https://mcp.example.com/oauth/callback"
+      },
       "allowedDomains": ["example.com"],
       "allowedOrigins": ["https://claude.ai"],
       "tokenTtl": "1h",
       "storage": "memory",
-      "googleClientId": {"$env": "GOOGLE_CLIENT_ID"},
-      "googleClientSecret": {"$env": "GOOGLE_CLIENT_SECRET"},
-      "googleRedirectUri": "https://mcp.example.com/oauth/callback",
       "jwtSecret": {"$env": "JWT_SECRET"},
       "encryptionKey": {"$env": "ENCRYPTION_KEY"}
     }

diff --git a/config-inline-test.json b/config-inline-test.json
@@ -7,13 +7,16 @@
     "auth": {
       "kind": "oauth",
       "issuer": "http://localhost:8080",
+      "idp": {
+        "provider": "google",
+        "clientId": {"$env": "GOOGLE_CLIENT_ID"},
+        "clientSecret": {"$env": "GOOGLE_CLIENT_SECRET"},
+        "redirectUri": "http://localhost:8080/oauth/callback"
+      },
       "allowedDomains": ["gmail.com"],
       "allowedOrigins": ["https://claude.ai"],
       "tokenTtl": "1h",
       "storage": "memory",
-      "googleClientId": {"$env": "GOOGLE_CLIENT_ID"},
-      "googleClientSecret": {"$env": "GOOGLE_CLIENT_SECRET"},
-      "googleRedirectUri": "http://localhost:8080/oauth/callback",
       "jwtSecret": {"$env": "JWT_SECRET"},
       "encryptionKey": {"$env": "ENCRYPTION_KEY"}
     }

diff --git a/config-oauth-firestore.example.json b/config-oauth-firestore.example.json
@@ -8,13 +8,16 @@
       "kind": "oauth",
       "issuer": {"$env": "OAUTH_ISSUER"},
       "gcpProject": {"$env": "GCP_PROJECT"},
+      "idp": {
+        "provider": "google",
+        "clientId": {"$env": "GOOGLE_CLIENT_ID"},
+        "clientSecret": {"$env": "GOOGLE_CLIENT_SECRET"},
+        "redirectUri": {"$env": "GOOGLE_REDIRECT_URI"}
+      },
       "allowedDomains": ["yourcompany.com", "contractors.yourcompany.com"],
       "allowedOrigins": ["https://claude.ai", "https://yourcompany.com"],
       "tokenTtl": "24h",
       "storage": "firestore",
-      "googleClientId": {"$env": "GOOGLE_CLIENT_ID"},
-      "googleClientSecret": {"$env": "GOOGLE_CLIENT_SECRET"},
-      "googleRedirectUri": {"$env": "GOOGLE_REDIRECT_URI"},
       "jwtSecret": {"$env": "JWT_SECRET"},
       "encryptionKey": {"$env": "ENCRYPTION_KEY"}
     }
@@ -25,11 +28,20 @@
       "command": "docker",
       "args": [
         "run", "--rm", "-i", "--network", "host",
-        "mcp/postgres",
-        {"$env": "DATABASE_URL"}
+        "-e", "POSTGRES_HOST",
+        "-e", "POSTGRES_PORT",
+        "-e", "POSTGRES_DATABASE",
+        "-e", "POSTGRES_USER",
+        "-e", "POSTGRES_PASSWORD",
+        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
+        "--stdio", "--prebuilt", "postgres"
       ],
       "env": {
-        "PGPASSWORD": {"$env": "POSTGRES_PASSWORD"}
+        "POSTGRES_HOST": {"$env": "POSTGRES_HOST"},
+        "POSTGRES_PORT": {"$env": "POSTGRES_PORT"},
+        "POSTGRES_DATABASE": {"$env": "POSTGRES_DATABASE"},
+        "POSTGRES_USER": {"$env": "POSTGRES_USER"},
+        "POSTGRES_PASSWORD": {"$env": "POSTGRES_PASSWORD"}
       }
     },
     "notion": {

diff --git a/config-oauth.example.json b/config-oauth.example.json
@@ -8,13 +8,16 @@
       "kind": "oauth",
       "issuer": {"$env": "OAUTH_ISSUER"},
       "gcpProject": {"$env": "GCP_PROJECT"},
+      "idp": {
+        "provider": "google",
+        "clientId": {"$env": "GOOGLE_CLIENT_ID"},
+        "clientSecret": {"$env": "GOOGLE_CLIENT_SECRET"},
+        "redirectUri": {"$env": "GOOGLE_REDIRECT_URI"}
+      },
       "allowedDomains": ["yourcompany.com", "contractors.yourcompany.com"],
       "allowedOrigins": ["https://claude.ai", "https://yourcompany.com"],
       "tokenTtl": "24h",
       "storage": "memory",
-      "googleClientId": {"$env": "GOOGLE_CLIENT_ID"},
-      "googleClientSecret": {"$env": "GOOGLE_CLIENT_SECRET"},
-      "googleRedirectUri": {"$env": "GOOGLE_REDIRECT_URI"},
       "jwtSecret": {"$env": "JWT_SECRET"},
       "encryptionKey": {"$env": "ENCRYPTION_KEY"}
     }
@@ -25,11 +28,20 @@
       "command": "docker",
       "args": [
         "run", "--rm", "-i", "--network", "host",
-        "mcp/postgres",
-        {"$env": "DATABASE_URL"}
+        "-e", "POSTGRES_HOST",
+        "-e", "POSTGRES_PORT",
+        "-e", "POSTGRES_DATABASE",
+        "-e", "POSTGRES_USER",
+        "-e", "POSTGRES_PASSWORD",
+        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
+        "--stdio", "--prebuilt", "postgres"
       ],
       "env": {
-        "PGPASSWORD": {"$env": "POSTGRES_PASSWORD"}
+        "POSTGRES_HOST": {"$env": "POSTGRES_HOST"},
+        "POSTGRES_PORT": {"$env": "POSTGRES_PORT"},
+        "POSTGRES_DATABASE": {"$env": "POSTGRES_DATABASE"},
+        "POSTGRES_USER": {"$env": "POSTGRES_USER"},
+        "POSTGRES_PASSWORD": {"$env": "POSTGRES_PASSWORD"}
       }
     },
     "notion": {

diff --git a/config-oauth.json b/config-oauth.json
@@ -8,26 +8,41 @@
       "kind": "oauth",
       "issuer": "https://mcp-internal.yourcompany.org",
       "gcpProject": {"$env": "GCP_PROJECT"},
+      "idp": {
+        "provider": "google",
+        "clientId": {"$env": "GOOGLE_CLIENT_ID"},
+        "clientSecret": {"$env": "GOOGLE_CLIENT_SECRET"},
+        "redirectUri": "https://mcp-internal.yourcompany.org/oauth/callback"
+      },
       "allowedDomains": ["yourcompany.com"],
       "allowedOrigins": ["https://claude.ai"],
       "tokenTtl": "24h",
       "storage": "memory",
-      "googleClientId": {"$env": "GOOGLE_CLIENT_ID"},
-      "googleClientSecret": {"$env": "GOOGLE_CLIENT_SECRET"},
-      "googleRedirectUri": "https://mcp-internal.yourcompany.org/oauth/callback",
       "jwtSecret": {"$env": "JWT_SECRET"},
       "encryptionKey": {"$env": "ENCRYPTION_KEY"}
     }
   },
   "mcpServers": {
     "postgres": {
       "transportType": "stdio",
-      "command": "docker", 
+      "command": "docker",
       "args": [
-        "run", "--rm", "-i",
-        "mcp/postgres:latest",
-        "postgresql://user:password@localhost:5432/database"
-      ]
+        "run", "--rm", "-i", "--network", "host",
+        "-e", "POSTGRES_HOST",
+        "-e", "POSTGRES_PORT",
+        "-e", "POSTGRES_DATABASE",
+        "-e", "POSTGRES_USER",
+        "-e", "POSTGRES_PASSWORD",
+        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
+        "--stdio", "--prebuilt", "postgres"
+      ],
+      "env": {
+        "POSTGRES_HOST": {"$env": "POSTGRES_HOST"},
+        "POSTGRES_PORT": {"$env": "POSTGRES_PORT"},
+        "POSTGRES_DATABASE": {"$env": "POSTGRES_DATABASE"},
+        "POSTGRES_USER": {"$env": "POSTGRES_USER"},
+        "POSTGRES_PASSWORD": {"$env": "POSTGRES_PASSWORD"}
+      }
     },
     "notion": {
       "transportType": "stdio",

diff --git a/config-token.example.json b/config-token.example.json
@@ -11,8 +11,13 @@
       "command": "docker",
       "args": [
         "run", "--rm", "-i", "--network", "host",
-        "mcp/postgres",
-        "postgresql://testuser:testpass@localhost:5432/testdb"
+        "-e", "POSTGRES_HOST=localhost",
+        "-e", "POSTGRES_PORT=5432",
+        "-e", "POSTGRES_DATABASE=testdb",
+        "-e", "POSTGRES_USER=testuser",
+        "-e", "POSTGRES_PASSWORD=testpass",
+        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
+        "--stdio", "--prebuilt", "postgres"
       ],
       "serviceAuths": [
         {

diff --git a/config-user-tokens-example.json b/config-user-tokens-example.json
@@ -8,13 +8,16 @@
       "kind": "oauth",
       "issuer": {"$env": "OAUTH_ISSUER"},
       "gcpProject": {"$env": "GCP_PROJECT"},
+      "idp": {
+        "provider": "google",
+        "clientId": {"$env": "GOOGLE_CLIENT_ID"},
+        "clientSecret": {"$env": "GOOGLE_CLIENT_SECRET"},
+        "redirectUri": {"$env": "GOOGLE_REDIRECT_URI"}
+      },
       "allowedDomains": ["yourcompany.com"],
       "allowedOrigins": ["https://claude.ai"],
       "tokenTtl": "24h",
       "storage": "memory",
-      "googleClientId": {"$env": "GOOGLE_CLIENT_ID"},
-      "googleClientSecret": {"$env": "GOOGLE_CLIENT_SECRET"},
-      "googleRedirectUri": {"$env": "GOOGLE_REDIRECT_URI"},
       "jwtSecret": {"$env": "JWT_SECRET"},
       "encryptionKey": {"$env": "ENCRYPTION_KEY"}
     }
@@ -57,11 +60,20 @@
       "command": "docker",
       "args": [
         "run", "--rm", "-i", "--network", "host",
-        "mcp/postgres",
-        {"$env": "DATABASE_URL"}
+        "-e", "POSTGRES_HOST",
+        "-e", "POSTGRES_PORT",
+        "-e", "POSTGRES_DATABASE",
+        "-e", "POSTGRES_USER",
+        "-e", "POSTGRES_PASSWORD",
+        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
+        "--stdio", "--prebuilt", "postgres"
       ],
       "env": {
-        "PGPASSWORD": {"$env": "POSTGRES_PASSWORD"}
+        "POSTGRES_HOST": {"$env": "POSTGRES_HOST"},
+        "POSTGRES_PORT": {"$env": "POSTGRES_PORT"},
+        "POSTGRES_DATABASE": {"$env": "POSTGRES_DATABASE"},
+        "POSTGRES_USER": {"$env": "POSTGRES_USER"},
+        "POSTGRES_PASSWORD": {"$env": "POSTGRES_PASSWORD"}
       }
     }
   }

diff --git a/docs-site/src/content/docs/configuration.md b/docs-site/src/content/docs/configuration.md
@@ -49,13 +49,16 @@ For production, use OAuth with Google. Claude redirects users to Google for auth
   "auth": {
     "kind": "oauth",
     "issuer": "https://mcp.company.com",
+    "idp": {
+      "provider": "google",
+      "clientId": { "$env": "GOOGLE_CLIENT_ID" },
+      "clientSecret": { "$env": "GOOGLE_CLIENT_SECRET" },
+      "redirectUri": "https://mcp.company.com/oauth/callback"
+    },
     "allowedDomains": ["company.com"],
     "allowedOrigins": ["https://claude.ai"],
     "tokenTtl": "24h",
     "storage": "memory",
-    "googleClientId": { "$env": "GOOGLE_CLIENT_ID" },
-    "googleClientSecret": { "$env": "GOOGLE_CLIENT_SECRET" },
-    "googleRedirectUri": "https://mcp.company.com/oauth/callback",
     "jwtSecret": { "$env": "JWT_SECRET" },
     "encryptionKey": { "$env": "ENCRYPTION_KEY" }
   }
@@ -66,7 +69,7 @@ The `issuer` should match your `baseURL`. `allowedDomains` restricts access to s
 
 `tokenTtl` controls how long JWT tokens are valid. Shorter times are more secure but require more frequent logins.
 
-Security requirements: `googleClientSecret`, `jwtSecret`, and `encryptionKey` must be environment variables. The JWT secret must be at least 32 bytes. The encryption key must be exactly 32 bytes.
+Security requirements: `idp.clientSecret`, `jwtSecret`, and `encryptionKey` must be environment variables. The JWT secret must be at least 32 bytes. The encryption key must be exactly 32 bytes.
 
 For production, set `storage` to "firestore" and add `gcpProject`, `firestoreDatabase`, and `firestoreCollection` fields.
 
@@ -345,13 +348,16 @@ Set `MCP_FRONT_ENV=development` when testing OAuth locally. It allows http:// UR
     "auth": {
       "kind": "oauth",
       "issuer": "https://mcp.company.com",
+      "idp": {
+        "provider": "google",
+        "clientId": { "$env": "GOOGLE_CLIENT_ID" },
+        "clientSecret": { "$env": "GOOGLE_CLIENT_SECRET" },
+        "redirectUri": "https://mcp.company.com/oauth/callback"
+      },
       "allowedDomains": ["company.com"],
       "allowedOrigins": ["https://claude.ai"],
       "tokenTtl": "4h",
       "storage": "firestore",
-      "googleClientId": { "$env": "GOOGLE_CLIENT_ID" },
-      "googleClientSecret": { "$env": "GOOGLE_CLIENT_SECRET" },
-      "googleRedirectUri": "https://mcp.company.com/oauth/callback",
       "jwtSecret": { "$env": "JWT_SECRET" },
       "encryptionKey": { "$env": "ENCRYPTION_KEY" },
       "gcpProject": { "$env": "GOOGLE_CLOUD_PROJECT" },