fix: remote mcp doc link and validation (#909)

* fix: callback_port required only for dynamic client registration

* fix: oauth label and link to doc

* fix: show pkce for oauth and oidc type

* leftover

Author: peppescg

renderer/src/common/lib/form-schema-mcp.ts

@@ -282,14 +282,7 @@ export const createMcpBaseSchema = (workloads: CoreWorkload[]) => {
 
 const remoteMcpOauthConfigSchema = z.object({
   authorize_url: z.string().optional(),
-  callback_port: z
-    .number()
-    .optional()
-    .refine(
-      (val) => val !== undefined && val !== null,
-      'Callback port is required'
-    ),
-
+  callback_port: z.number().optional(),
   client_id: z.string().optional(),
   client_secret: z
     .object({

renderer/src/common/lib/workloads/remote/form-schema-remote-mcp.ts

@@ -19,11 +19,6 @@ const OAUTH_VALIDATION_RULES = {
       message: 'Client ID is required for OAuth2',
       path: ['oauth_config', 'client_id'],
     },
-    {
-      field: 'client_secret',
-      message: 'Client Secret is required for OAuth2',
-      path: ['oauth_config', 'client_secret'],
-    },
   ],
   oidc: [
     {
@@ -49,6 +44,9 @@ const validateClientSecretField = (
 ): boolean =>
   Boolean(value && value.value.secret && value.value.secret.trim() !== '')
 
+const validateCallbackPortField = (value: number | undefined): boolean =>
+  Boolean(value !== undefined && value !== null && value > 0)
+
 export const getFormSchemaRemoteMcp = (
   workloads: CoreWorkload[],
   editingServerName?: string
@@ -61,9 +59,19 @@ export const getFormSchemaRemoteMcp = (
     (data, ctx) => {
       const { auth_type, oauth_config } = data
 
-      // Skip validation if no authentication is required
-      if (auth_type === 'none') return
+      // Validate callback_port is required when auth_type is 'none'
+      if (auth_type === 'none') {
+        if (!validateCallbackPortField(oauth_config?.callback_port)) {
+          ctx.addIssue({
+            code: 'custom',
+            message: 'Callback port is required',
+            path: ['oauth_config', 'callback_port'],
+          })
+        }
+        return
+      }
 
+      // Validate OAuth/OIDC specific fields
       const validationRules =
         OAUTH_VALIDATION_RULES[auth_type as keyof typeof OAUTH_VALIDATION_RULES]
 

renderer/src/features/mcp-servers/components/remote-mcp/dialog-form-remote-mcp.tsx

@@ -344,7 +344,7 @@ export function DialogFormRemoteMcp({
                         rel="noopener noreferrer"
                         className="flex cursor-pointer items-center gap-1
                           underline"
-                        href="https://docs.stacklok.com/toolhive/guides-ui/run-mcp-servers#remote-mcp-server"
+                        href="https://docs.stacklok.com/toolhive/guides-ui/run-mcp-servers#custom-mcp-server"
                         target="_blank"
                       >
                         documentation <ExternalLinkIcon size={12} />
@@ -364,7 +364,7 @@ export function DialogFormRemoteMcp({
                         <SelectItem value="none">
                           Dynamic Client Registration
                         </SelectItem>
-                        <SelectItem value="oauth2">OAuth2</SelectItem>
+                        <SelectItem value="oauth2">OAuth 2.0</SelectItem>
                         <SelectItem value="oidc">OIDC</SelectItem>
                       </SelectContent>
                     </Select>

renderer/src/features/mcp-servers/components/remote-mcp/form-fields-auth.tsx

@@ -7,17 +7,11 @@ import {
 } from '@/common/components/ui/form'
 import { Input } from '@/common/components/ui/input'
 import { TooltipInfoIcon } from '@/common/components/ui/tooltip-info-icon'
-import {
-  Select,
-  SelectTrigger,
-  SelectValue,
-  SelectContent,
-  SelectItem,
-} from '@/common/components/ui/select'
 import { type UseFormReturn } from 'react-hook-form'
 import { SecretStoreCombobox } from '@/common/components/secrets/secret-store-combobox'
 import type { FormSchemaRemoteMcp } from '@/common/lib/workloads/remote/form-schema-remote-mcp'
 import { cn } from '@/common/lib/utils'
+import { Checkbox } from '@/common/components/ui/checkbox'
 
 function ClientAuthFields({
   form,
@@ -90,7 +84,6 @@ function ClientAuthFields({
                 >
                   <div>
                     <FormLabel
-                      required={true}
                       htmlFor={`oauth_config.client_secret.value`}
                       className={cn(
                         `text-muted-foreground !border-input h-full items-center
@@ -222,38 +215,6 @@ export function FormFieldsAuth({
           />
 
           <ClientAuthFields form={form} authType={authType} />
-
-          <FormField
-            control={form.control}
-            name="oauth_config.use_pkce"
-            render={({ field }) => (
-              <FormItem>
-                <div className="flex items-center gap-1">
-                  <FormLabel htmlFor={field.name}>PKCE</FormLabel>
-                  <TooltipInfoIcon>
-                    Proof Key for Code Exchange (RFC 7636), automatically
-                    enables PKCE flow without client_secret.
-                  </TooltipInfoIcon>
-                </div>
-                <FormControl>
-                  <Select
-                    onValueChange={(value) => field.onChange(value === 'true')}
-                    value={field.value ? 'true' : 'false'}
-                    name={field.name}
-                  >
-                    <SelectTrigger id={field.name} className="w-full">
-                      <SelectValue placeholder="Select PKCE" />
-                    </SelectTrigger>
-                    <SelectContent>
-                      <SelectItem value="true">True</SelectItem>
-                      <SelectItem value="false">False</SelectItem>
-                    </SelectContent>
-                  </Select>
-                </FormControl>
-                <FormMessage />
-              </FormItem>
-            )}
-          />
         </>
       )}
 
@@ -349,6 +310,35 @@ export function FormFieldsAuth({
           />
         </>
       )}
+
+      {authType !== 'none' && (
+        <FormField
+          control={form.control}
+          name="oauth_config.use_pkce"
+          render={({ field }) => (
+            <FormItem>
+              <div className="flex items-center gap-1">
+                <FormLabel htmlFor={field.name}>PKCE</FormLabel>
+                <TooltipInfoIcon>
+                  Proof Key for Code Exchange (RFC 7636), automatically enables
+                  PKCE flow without client_secret.
+                </TooltipInfoIcon>
+              </div>
+              <FormControl>
+                <Checkbox
+                  id={field.name}
+                  name={field.name}
+                  checked={field.value}
+                  onCheckedChange={(checked) => {
+                    field.onChange(checked)
+                  }}
+                />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+      )}
     </>
   )
 }

renderer/src/features/registry-servers/components/__tests__/dialog-form-remote-registry-mcp.test.tsx

@@ -205,7 +205,7 @@ describe('DialogFormRemoteRegistryMcp', () => {
 
     await userEvent.click(
       screen.getByRole('option', {
-        name: /oauth2/i,
+        name: 'OAuth 2.0',
       })
     )
 
@@ -306,7 +306,7 @@ describe('DialogFormRemoteRegistryMcp', () => {
 
     // Select OAuth2 authentication
     await userEvent.click(screen.getByLabelText('Authorization method'))
-    await userEvent.click(screen.getByRole('option', { name: 'OAuth2' }))
+    await userEvent.click(screen.getByRole('option', { name: 'OAuth 2.0' }))
 
     // OAuth2 fields should now be visible
     await waitFor(() => {
@@ -377,7 +377,7 @@ describe('DialogFormRemoteRegistryMcp', () => {
 
     // Select OAuth2 authentication
     await userEvent.click(screen.getByLabelText('Authorization method'))
-    await userEvent.click(screen.getByRole('option', { name: 'OAuth2' }))
+    await userEvent.click(screen.getByRole('option', { name: 'OAuth 2.0' }))
 
     // Secrets section should be hidden for OAuth2
     await waitFor(() => {

renderer/src/features/registry-servers/components/dialog-form-remote-registry-mcp.tsx

@@ -35,6 +35,7 @@ import {
   SelectContent,
   SelectItem,
 } from '@/common/components/ui/select'
+import { ExternalLinkIcon } from 'lucide-react'
 
 const DEFAULT_FORM_VALUES: FormSchemaRemoteMcp = {
   name: '',
@@ -105,9 +106,7 @@ export function DialogFormRemoteRegistryMcp({
   const workloads = data?.workloads ?? []
 
   const form = useForm<FormSchemaRemoteMcp>({
-    resolver: zodV4Resolver(
-      getFormSchemaRemoteMcp(workloads, server?.name || undefined)
-    ),
+    resolver: zodV4Resolver(getFormSchemaRemoteMcp(workloads)),
     defaultValues: DEFAULT_FORM_VALUES,
     reValidateMode: 'onChange',
     mode: 'onChange',
@@ -288,7 +287,16 @@ export function DialogFormRemoteRegistryMcp({
                     </FormLabel>
                     <TooltipInfoIcon>
                       The authorization method the MCP server uses to
-                      authenticate clients.
+                      authenticate clients. Refer to the{' '}
+                      <a
+                        rel="noopener noreferrer"
+                        className="flex cursor-pointer items-center gap-1
+                          underline"
+                        href="https://docs.stacklok.com/toolhive/guides-ui/run-mcp-servers#configure-server"
+                        target="_blank"
+                      >
+                        documentation <ExternalLinkIcon size={12} />
+                      </a>
                     </TooltipInfoIcon>
                   </div>
                   <FormControl>
@@ -301,8 +309,10 @@ export function DialogFormRemoteRegistryMcp({
                         <SelectValue placeholder="Select authorization method" />
                       </SelectTrigger>
                       <SelectContent>
-                        <SelectItem value="none">None</SelectItem>
-                        <SelectItem value="oauth2">OAuth2</SelectItem>
+                        <SelectItem value="none">
+                          Dynamic Client Registration
+                        </SelectItem>
+                        <SelectItem value="oauth2">OAuth 2.0</SelectItem>
                         <SelectItem value="oidc">OIDC</SelectItem>
                       </SelectContent>
                     </Select>