zudoku 0.83.0 → 0.83.1

package/dist/cli/cli.js

@@ -5104,6 +5104,11 @@ var OperationItem = builder.objectRef("OperationItem").implement({
     operationId: t.exposeString("operationId", { nullable: true }),
     summary: t.exposeString("summary", { nullable: true }),
     description: t.exposeString("description", { nullable: true }),
+    // Lean flag so consumers (e.g. the sidebar) can tell an MCP server
+    // endpoint apart without pulling in the whole `x-mcp-server` extension.
+    isMcpServer: t.boolean({
+      resolve: (parent) => resolveExtensions(parent)["x-mcp-server"] !== void 0
+    }),
     contentTypes: t.stringList({
       resolve: (parent) => Object.keys(parent.requestBody?.content ?? {})
     }),

package/dist/declarations/lib/components/Search.d.ts

@@ -1,3 +1,5 @@
+import { type PropsWithChildren } from "react";
+export declare const SearchProvider: ({ children }: PropsWithChildren) => import("react").JSX.Element;
 export declare const Search: ({ className }: {
     className?: string;
 }) => import("react").JSX.Element | null;

package/dist/declarations/lib/core/plugins.d.ts

@@ -23,6 +23,7 @@ export interface ApiIdentityPlugin {
 export interface SearchProviderPlugin {
     renderSearch: (o: {
         isOpen: boolean;
+        onOpen: () => void;
         onClose: () => void;
     }) => React.JSX.Element | null;
 }

package/dist/declarations/lib/plugins/openapi/graphql/gql.d.ts

@@ -4,5 +4,5 @@ export declare function graphql(source: "\n  query OperationsForTag(\n    $input
 export declare function graphql(source: "\n  query SchemaInfo($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      servers {\n        url\n        description\n      }\n      license {\n        name\n        url\n        identifier\n      }\n      termsOfService\n      externalDocs {\n        description\n        url\n      }\n      contact {\n        name\n        url\n        email\n      }\n      description\n      summary\n      title\n      url\n      version\n      tags {\n        name\n        description\n        extensions\n      }\n      components {\n        securitySchemes {\n          name\n          type\n          description\n          in\n          paramName\n          scheme\n          bearerFormat\n          openIdConnectUrl\n          flows {\n            implicit {\n              authorizationUrl\n              scopes {\n                name\n                description\n              }\n            }\n            password {\n              tokenUrl\n              scopes {\n                name\n                description\n              }\n            }\n            clientCredentials {\n              tokenUrl\n              scopes {\n                name\n                description\n              }\n            }\n            authorizationCode {\n              authorizationUrl\n              tokenUrl\n              scopes {\n                name\n                description\n              }\n            }\n          }\n        }\n      }\n      webhooks {\n        name\n        method\n        summary\n        description\n      }\n    }\n  }\n"): typeof import("./graphql.js").SchemaInfoDocument;
 export declare function graphql(source: "\n  query GetSchemas($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      title\n      description\n      summary\n      components {\n        schemas {\n          name\n          schema\n          extensions\n        }\n      }\n    }\n  }\n"): typeof import("./graphql.js").GetSchemasDocument;
 export declare function graphql(source: "\n  query getServerQuery($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      url\n      servers {\n        url\n      }\n    }\n  }\n"): typeof import("./graphql.js").GetServerQueryDocument;
-export declare function graphql(source: "\n  query GetNavigationOperations($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      extensions\n      description\n      tags {\n        slug\n        name\n        extensions\n        operations {\n          summary\n          slug\n          method\n          operationId\n          path\n        }\n      }\n      components {\n        schemas {\n          __typename\n        }\n      }\n    }\n  }\n"): typeof import("./graphql.js").GetNavigationOperationsDocument;
+export declare function graphql(source: "\n  query GetNavigationOperations($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      extensions\n      description\n      tags {\n        slug\n        name\n        extensions\n        operations {\n          summary\n          slug\n          method\n          operationId\n          path\n          isMcpServer\n        }\n      }\n      components {\n        schemas {\n          __typename\n        }\n      }\n    }\n  }\n"): typeof import("./graphql.js").GetNavigationOperationsDocument;
 export declare function graphql(source: "\n  query SchemaWarmup($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      openapi\n    }\n  }\n"): typeof import("./graphql.js").SchemaWarmupDocument;

package/dist/declarations/lib/plugins/openapi/graphql/graphql.d.ts

@@ -314,6 +314,7 @@ export type GetNavigationOperationsQuery = {
                 method: string;
                 operationId: string | null;
                 path: string;
+                isMcpServer: boolean;
             }>;
         }>;
         components: {

package/dist/declarations/lib/plugins/openapi/mcp-configs.d.ts

@@ -19,7 +19,7 @@ export interface McpApp {
 export declare const MCP_APPS: McpApp[];
 export declare const getVisibleApps: (authType: AuthType) => McpApp[];
 export declare const getMcpServerName: (data?: McpServerData, summary?: string) => string;
-export declare const getMcpUrl: (serverUrl?: string, operationPath?: string) => string;
+export declare const getMcpUrl: (serverUrl?: string, operationPath?: string, data?: McpServerData) => string;
 export declare const getClaudeCodeCommand: (name: string, mcpUrl: string, auth?: AuthHeader) => string;
 export declare const getCodexCliCommand: (name: string, mcpUrl: string, auth?: AuthHeader) => string;
 export declare const getCursorConfig: (name: string, mcpUrl: string, auth?: AuthHeader) => string;

package/docs/configuration/search.md

@@ -182,6 +182,11 @@ You can also pass
 Zudoku's defaults and passed through to Inkeep as-is, so any option Inkeep supports can be used —
 including ones added after this Zudoku version was released.
 
+Zudoku owns the search modal's open state, so `modalSettings.isOpen` is managed for you. The
+<kbd>⌘</kbd>+<kbd>K</kbd> / <kbd>Ctrl</kbd>+<kbd>K</kbd> shortcut is handled by Zudoku's search
+button as well, which is why Inkeep's own `shortcutKey` is disabled by default. Setting it adds an
+additional shortcut rather than replacing it.
+
 For example, to categorize results into tabs based on their URL:
 
 ```typescript

package/docs/guides/mcp-servers.md

@@ -59,6 +59,7 @@ metadata. In this case, the operation's `summary` is used as the server name.
 | --------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
 | `name`    | `string` | No       | Display name used in the generated client configuration snippets. Falls back to the operation `summary`, then `"mcp-server"` |
 | `version` | `string` | No       | Version metadata (included for completeness; not currently rendered in UI)                                                   |
+| `url`     | `string` | No       | Overrides the endpoint URL shown in the card and install snippets                                                            |
 | `tools`   | `array`  | No       | Tools metadata (used by Zuplo enrichment; not currently rendered in UI)                                                      |
 
 Each tool in the `tools` array has:
@@ -92,6 +93,20 @@ For example, with this configuration:
 
 The displayed MCP URL will be `https://api.example.com/mcp/docs`.
 
+If your MCP server lives on its own hostname, set `url` on the extension to override the derived
+endpoint:
+
+```json
+{
+  "x-mcp-server": { "name": "docs-mcp", "url": "https://mcp.example.com/mcp" }
+}
+```
+
+An absolute URL is used verbatim everywhere the endpoint appears, and takes precedence over the
+server dropdown. A value without a scheme (such as `/v2/mcp`) is treated as a path on the server URL
+instead. See the
+[`x-mcp-server` reference](/docs/openapi-extensions/x-mcp-server#overriding-the-url) for details.
+
 ## Complete example
 
 This is a minimal but complete OpenAPI spec that produces an MCP endpoint page:

package/docs/openapi-extensions/x-mcp-server.md

@@ -32,6 +32,7 @@ When using the object form, the following properties are available:
 | --------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
 | `name`    | `string`        | No       | Display name used in the generated client configuration snippets. Falls back to the operation `summary`, then `"mcp-server"` |
 | `version` | `string`        | No       | Version metadata                                                                                                             |
+| `url`     | `string`        | No       | Overrides the endpoint URL shown in the card and install snippets. See [MCP URL resolution](#mcp-url-resolution)             |
 | `tools`   | `[Tool Object]` | No       | Array of tools provided by the MCP server                                                                                    |
 
 Each item in the `tools` array:
@@ -47,6 +48,35 @@ The displayed MCP URL is constructed from the **server URL** of the API and the
 operation. The server URL comes from the OpenAPI `servers` array (or the operation-level `servers`
 override if present).
 
+### Overriding the URL
+
+Set `url` on `x-mcp-server` when the MCP server is not reachable under the documented API server —
+for example when it runs on its own hostname:
+
+```yaml
+servers:
+  - url: https://api.example.com
+paths:
+  /mcp:
+    post:
+      summary: My MCP Server
+      x-mcp-server:
+        name: my-mcp-server
+        url: https://mcp.example.com/mcp
+      responses:
+        "200":
+          description: MCP response
+```
+
+The card and every install snippet then use `https://mcp.example.com/mcp` instead of
+`https://api.example.com/mcp`.
+
+An absolute `url` (one with a scheme, such as `https://`) replaces the endpoint entirely and is used
+verbatim — it also takes precedence over the server picked in the server dropdown, since it names a
+host of its own. A value without a scheme is treated as a path on the server URL instead, so
+`url: /v2/mcp` resolves to `https://api.example.com/v2/mcp` and still follows server selection.
+Blank values are ignored and the URL falls back to the server URL plus the operation path.
+
 ## Examples
 
 ### Boolean shorthand

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zudoku",
-  "version": "0.83.0",
+  "version": "0.83.1",
   "type": "module",
   "engines": {
     "node": ">=22.22.0"

package/src/lib/components/Header.tsx

@@ -25,7 +25,7 @@ import { useZudoku } from "./context/ZudokuContext.js";
 import { HeaderNavigation } from "./HeaderNavigation.js";
 import { MobileTopNavigation } from "./MobileTopNavigation.js";
 import { PageProgress } from "./PageProgress.js";
-import { Search } from "./Search.js";
+import { Search, SearchProvider } from "./Search.js";
 import { Slot } from "./Slot.js";
 import { ThemeSwitch } from "./ThemeSwitch.js";
 import { TopNavigation } from "./TopNavigation.js";
@@ -151,102 +151,106 @@ export const Header = memo(function HeaderInner() {
   const borderBottom = "inset-shadow-[0_-1px_0_0_var(--border)]";
 
   return (
-    <header
-      className="sticky lg:top-0 z-10 bg-background/80 backdrop-blur w-full"
-      data-pagefind-ignore="all"
-    >
-      <Banner />
-      <div className={cn(borderBottom, "relative")}>
-        <PageProgress />
-        <div className="max-w-screen-2xl mx-auto flex lg:grid lg:grid-cols-[1fr_auto_1fr] gap-2 items-center justify-between h-(--top-header-height) px-4 lg:px-8 border-transparent">
-          <div className="flex items-center gap-4 min-w-0 justify-self-start">
-            <Link
-              to={site?.logo?.href ?? "/"}
-              reloadDocument={site?.logo?.reloadDocument ?? true}
-              className="shrink-0"
-            >
-              <div className="flex items-center gap-3.5">
-                {site?.logo ? (
-                  <>
-                    <Head>
-                      <link rel="preload" as="image" href={logoLightSrc} />
-                      <link rel="preload" as="image" href={logoDarkSrc} />
-                    </Head>
-                    <img
-                      src={logoLightSrc}
-                      alt={site.logo.alt ?? site.title}
-                      style={{ width: site.logo.width }}
-                      className="max-h-(--top-header-height) dark:hidden"
-                    />
-                    <img
-                      src={logoDarkSrc}
-                      alt={site.logo.alt ?? site.title}
-                      style={{ width: site.logo.width }}
-                      className="max-h-(--top-header-height) hidden dark:block"
-                    />
-                  </>
-                ) : (
-                  <span className="font-semibold text-2xl">{site?.title}</span>
-                )}
-              </div>
-            </Link>
-            <Slot.Target name="head-navigation-start" />
-            {searchPosition === "start" && (
-              <Search className="hidden lg:flex" />
-            )}
-            {authPosition === "start" && (
-              <div className="hidden lg:flex">
-                <ProfileMenu />
-              </div>
-            )}
-            {navPosition === "start" && (
-              <div className="hidden lg:block min-w-0">
-                <HeaderNavigation />
-              </div>
-            )}
-          </div>
-
-          <div className="flex items-center justify-center">
-            <Search
-              className={cn(
-                searchPosition === "center" ? "flex" : "flex lg:hidden",
+    <SearchProvider>
+      <header
+        className="sticky lg:top-0 z-10 bg-background/80 backdrop-blur w-full"
+        data-pagefind-ignore="all"
+      >
+        <Banner />
+        <div className={cn(borderBottom, "relative")}>
+          <PageProgress />
+          <div className="max-w-screen-2xl mx-auto flex lg:grid lg:grid-cols-[1fr_auto_1fr] gap-2 items-center justify-between h-(--top-header-height) px-4 lg:px-8 border-transparent">
+            <div className="flex items-center gap-4 min-w-0 justify-self-start">
+              <Link
+                to={site?.logo?.href ?? "/"}
+                reloadDocument={site?.logo?.reloadDocument ?? true}
+                className="shrink-0"
+              >
+                <div className="flex items-center gap-3.5">
+                  {site?.logo ? (
+                    <>
+                      <Head>
+                        <link rel="preload" as="image" href={logoLightSrc} />
+                        <link rel="preload" as="image" href={logoDarkSrc} />
+                      </Head>
+                      <img
+                        src={logoLightSrc}
+                        alt={site.logo.alt ?? site.title}
+                        style={{ width: site.logo.width }}
+                        className="max-h-(--top-header-height) dark:hidden"
+                      />
+                      <img
+                        src={logoDarkSrc}
+                        alt={site.logo.alt ?? site.title}
+                        style={{ width: site.logo.width }}
+                        className="max-h-(--top-header-height) hidden dark:block"
+                      />
+                    </>
+                  ) : (
+                    <span className="font-semibold text-2xl">
+                      {site?.title}
+                    </span>
+                  )}
+                </div>
+              </Link>
+              <Slot.Target name="head-navigation-start" />
+              {searchPosition === "start" && (
+                <Search className="hidden lg:flex" />
               )}
-            />
-            {navPosition === "center" && (
-              <div className="hidden lg:block min-w-0">
-                <HeaderNavigation />
-              </div>
-            )}
-            {authPosition === "center" && (
-              <div className="hidden lg:flex">
-                <ProfileMenu />
-              </div>
-            )}
-          </div>
+              {authPosition === "start" && (
+                <div className="hidden lg:flex">
+                  <ProfileMenu />
+                </div>
+              )}
+              {navPosition === "start" && (
+                <div className="hidden lg:block min-w-0">
+                  <HeaderNavigation />
+                </div>
+              )}
+            </div>
 
-          <div className="flex items-center gap-2 justify-self-end">
-            <MobileTopNavigation />
-            <div className="hidden lg:flex items-center text-sm gap-2">
-              {navPosition === "end" && (
-                <div className="min-w-0">
+            <div className="flex items-center justify-center">
+              <Search
+                className={cn(
+                  searchPosition === "center" ? "flex" : "flex lg:hidden",
+                )}
+              />
+              {navPosition === "center" && (
+                <div className="hidden lg:block min-w-0">
                   <HeaderNavigation />
                 </div>
               )}
-              {authPosition === "end" && <ProfileMenu />}
-              {searchPosition === "end" && <Search />}
-              <Slot.Target name="head-navigation-end" />
-              {themeSwitcherEnabled && <ThemeSwitch />}
+              {authPosition === "center" && (
+                <div className="hidden lg:flex">
+                  <ProfileMenu />
+                </div>
+              )}
+            </div>
+
+            <div className="flex items-center gap-2 justify-self-end">
+              <MobileTopNavigation />
+              <div className="hidden lg:flex items-center text-sm gap-2">
+                {navPosition === "end" && (
+                  <div className="min-w-0">
+                    <HeaderNavigation />
+                  </div>
+                )}
+                {authPosition === "end" && <ProfileMenu />}
+                {searchPosition === "end" && <Search />}
+                <Slot.Target name="head-navigation-end" />
+                {themeSwitcherEnabled && <ThemeSwitch />}
+              </div>
             </div>
           </div>
         </div>
-      </div>
-      <div className={cn("hidden lg:block", borderBottom)}>
-        <div className="max-w-screen-2xl mx-auto border-transparent relative">
-          <Slot.Target name="top-navigation-before" />
-          <TopNavigation />
-          <Slot.Target name="top-navigation-after" />
+        <div className={cn("hidden lg:block", borderBottom)}>
+          <div className="max-w-screen-2xl mx-auto border-transparent relative">
+            <Slot.Target name="top-navigation-before" />
+            <TopNavigation />
+            <Slot.Target name="top-navigation-after" />
+          </div>
         </div>
-      </div>
-    </header>
+      </header>
+    </SearchProvider>
   );
 });

package/src/lib/components/Search.tsx

@@ -1,5 +1,14 @@
 import { SearchIcon } from "lucide-react";
-import { Suspense, useCallback, useEffect, useState } from "react";
+import {
+  createContext,
+  type PropsWithChildren,
+  Suspense,
+  use,
+  useCallback,
+  useEffect,
+  useMemo,
+  useState,
+} from "react";
 import { isSearchPlugin } from "../core/plugins.js";
 import { focusRing } from "../ui/util.js";
 import { cn } from "../util/cn.js";
@@ -7,40 +16,70 @@ import { getOS } from "../util/os.js";
 import { ClientOnly } from "./ClientOnly.js";
 import { useZudoku } from "./context/ZudokuContext.js";
 
-export const Search = ({ className }: { className?: string }) => {
+/** `null` when no search plugin is configured, `undefined` outside a provider */
+const SearchContext = createContext<{ onOpen: () => void } | null | undefined>(
+  undefined,
+);
+
+/**
+ * Owns the search modal and the ⌘K / Ctrl+K shortcut for all `Search` buttons
+ * below it. The header renders a button per breakpoint and placement, so
+ * keeping this per button would open one modal for each of them.
+ */
+export const SearchProvider = ({ children }: PropsWithChildren) => {
   const ctx = useZudoku();
   const [isOpen, setIsOpen] = useState(false);
   const onOpen = useCallback(() => setIsOpen(true), []);
   const onClose = useCallback(() => setIsOpen(false), []);
 
+  const searchPlugin = ctx.options.plugins?.find(isSearchPlugin);
+
   useEffect(() => {
-    if (isOpen) {
-      return;
-    }
+    if (isOpen || !searchPlugin) return;
 
-    function onKeyDown(event: KeyboardEvent) {
+    const onKeyDown = (event: KeyboardEvent) => {
       if (event.key === "k" && (event.metaKey || event.ctrlKey)) {
         event.preventDefault();
         setIsOpen(true);
       }
-    }
+    };
 
     window.addEventListener("keydown", onKeyDown);
 
-    return () => {
-      window.removeEventListener("keydown", onKeyDown);
-    };
-  }, [isOpen]);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, [isOpen, searchPlugin]);
 
-  const searchPlugin = ctx.options.plugins?.find(isSearchPlugin);
+  const value = useMemo(
+    () => (searchPlugin ? { onOpen } : null),
+    [searchPlugin, onOpen],
+  );
+
+  return (
+    <SearchContext value={value}>
+      {children}
+      {searchPlugin && (
+        <Suspense>
+          {searchPlugin.renderSearch({ isOpen, onOpen, onClose })}
+        </Suspense>
+      )}
+    </SearchContext>
+  );
+};
+
+export const Search = ({ className }: { className?: string }) => {
+  const search = use(SearchContext);
+
+  if (search === undefined) {
+    throw new Error("Search must be used within a SearchProvider.");
+  }
 
-  if (!searchPlugin) return null;
+  if (!search) return null;
 
   return (
     <div className={className}>
       <button
         type="button"
-        onClick={onOpen}
+        onClick={search.onOpen}
         className={cn(
           "relative w-full md:w-56 flex items-center border bg-clip-padding h-8 rounded-lg px-3 pr-14 text-sm transition-all",
           "border-input text-muted-foreground bg-background hover:bg-muted/50 hover:text-foreground shadow-xs",
@@ -55,7 +94,6 @@ export const Search = ({ className }: { className?: string }) => {
           <KbdShortcut />
         </ClientOnly>
       </button>
-      <Suspense>{searchPlugin.renderSearch({ isOpen, onClose })}</Suspense>
     </div>
   );
 };

package/src/lib/core/plugins.ts

@@ -46,6 +46,7 @@ export interface ApiIdentityPlugin {
 export interface SearchProviderPlugin {
   renderSearch: (o: {
     isOpen: boolean;
+    onOpen: () => void;
     onClose: () => void;
   }) => React.JSX.Element | null;
 }

package/src/lib/oas/graphql/index.ts

@@ -711,6 +711,12 @@ const OperationItem = builder
       operationId: t.exposeString("operationId", { nullable: true }),
       summary: t.exposeString("summary", { nullable: true }),
       description: t.exposeString("description", { nullable: true }),
+      // Lean flag so consumers (e.g. the sidebar) can tell an MCP server
+      // endpoint apart without pulling in the whole `x-mcp-server` extension.
+      isMcpServer: t.boolean({
+        resolve: (parent) =>
+          resolveExtensions(parent)["x-mcp-server"] !== undefined,
+      }),
       contentTypes: t.stringList({
         resolve: (parent) => Object.keys(parent.requestBody?.content ?? {}),
       }),

package/src/lib/plugins/openapi/MCPEndpoint.tsx

@@ -92,7 +92,7 @@ export const MCPEndpoint = ({
   summary?: string;
 }) => {
   const [isCopied, setIsCopied] = useState(false);
-  const mcpUrl = getMcpUrl(serverUrl, operationPath);
+  const mcpUrl = getMcpUrl(serverUrl, operationPath, data);
   const name = getMcpServerName(data, summary);
   const auth = getAuthHeader(data);
   const authType = getAuthType(data);

package/src/lib/plugins/openapi/graphql/gql.ts

@@ -19,7 +19,7 @@ type Documents = {
   "\n  query SchemaInfo($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      servers {\n        url\n        description\n      }\n      license {\n        name\n        url\n        identifier\n      }\n      termsOfService\n      externalDocs {\n        description\n        url\n      }\n      contact {\n        name\n        url\n        email\n      }\n      description\n      summary\n      title\n      url\n      version\n      tags {\n        name\n        description\n        extensions\n      }\n      components {\n        securitySchemes {\n          name\n          type\n          description\n          in\n          paramName\n          scheme\n          bearerFormat\n          openIdConnectUrl\n          flows {\n            implicit {\n              authorizationUrl\n              scopes {\n                name\n                description\n              }\n            }\n            password {\n              tokenUrl\n              scopes {\n                name\n                description\n              }\n            }\n            clientCredentials {\n              tokenUrl\n              scopes {\n                name\n                description\n              }\n            }\n            authorizationCode {\n              authorizationUrl\n              tokenUrl\n              scopes {\n                name\n                description\n              }\n            }\n          }\n        }\n      }\n      webhooks {\n        name\n        method\n        summary\n        description\n      }\n    }\n  }\n": typeof types.SchemaInfoDocument;
   "\n  query GetSchemas($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      title\n      description\n      summary\n      components {\n        schemas {\n          name\n          schema\n          extensions\n        }\n      }\n    }\n  }\n": typeof types.GetSchemasDocument;
   "\n  query getServerQuery($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      url\n      servers {\n        url\n      }\n    }\n  }\n": typeof types.GetServerQueryDocument;
-  "\n  query GetNavigationOperations($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      extensions\n      description\n      tags {\n        slug\n        name\n        extensions\n        operations {\n          summary\n          slug\n          method\n          operationId\n          path\n        }\n      }\n      components {\n        schemas {\n          __typename\n        }\n      }\n    }\n  }\n": typeof types.GetNavigationOperationsDocument;
+  "\n  query GetNavigationOperations($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      extensions\n      description\n      tags {\n        slug\n        name\n        extensions\n        operations {\n          summary\n          slug\n          method\n          operationId\n          path\n          isMcpServer\n        }\n      }\n      components {\n        schemas {\n          __typename\n        }\n      }\n    }\n  }\n": typeof types.GetNavigationOperationsDocument;
   "\n  query SchemaWarmup($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      openapi\n    }\n  }\n": typeof types.SchemaWarmupDocument;
 };
 const documents: Documents = {
@@ -35,7 +35,7 @@ const documents: Documents = {
     types.GetSchemasDocument,
   "\n  query getServerQuery($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      url\n      servers {\n        url\n      }\n    }\n  }\n":
     types.GetServerQueryDocument,
-  "\n  query GetNavigationOperations($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      extensions\n      description\n      tags {\n        slug\n        name\n        extensions\n        operations {\n          summary\n          slug\n          method\n          operationId\n          path\n        }\n      }\n      components {\n        schemas {\n          __typename\n        }\n      }\n    }\n  }\n":
+  "\n  query GetNavigationOperations($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      extensions\n      description\n      tags {\n        slug\n        name\n        extensions\n        operations {\n          summary\n          slug\n          method\n          operationId\n          path\n          isMcpServer\n        }\n      }\n      components {\n        schemas {\n          __typename\n        }\n      }\n    }\n  }\n":
     types.GetNavigationOperationsDocument,
   "\n  query SchemaWarmup($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      openapi\n    }\n  }\n":
     types.SchemaWarmupDocument,
@@ -81,7 +81,7 @@ export function graphql(
  * The graphql function is used to parse GraphQL queries into a document that can be used by GraphQL clients.
  */
 export function graphql(
-  source: "\n  query GetNavigationOperations($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      extensions\n      description\n      tags {\n        slug\n        name\n        extensions\n        operations {\n          summary\n          slug\n          method\n          operationId\n          path\n        }\n      }\n      components {\n        schemas {\n          __typename\n        }\n      }\n    }\n  }\n",
+  source: "\n  query GetNavigationOperations($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      extensions\n      description\n      tags {\n        slug\n        name\n        extensions\n        operations {\n          summary\n          slug\n          method\n          operationId\n          path\n          isMcpServer\n        }\n      }\n      components {\n        schemas {\n          __typename\n        }\n      }\n    }\n  }\n",
 ): typeof import("./graphql.js").GetNavigationOperationsDocument;
 /**
  * The graphql function is used to parse GraphQL queries into a document that can be used by GraphQL clients.

package/src/lib/plugins/openapi/graphql/graphql.ts

@@ -281,6 +281,7 @@ export type GetNavigationOperationsQuery = {
         method: string;
         operationId: string | null;
         path: string;
+        isMcpServer: boolean;
       }>;
     }>;
     components: { schemas: Array<{ __typename: "SchemaItem" }> | null } | null;
@@ -731,6 +732,7 @@ export const GetNavigationOperationsDocument = new TypedDocumentString(`
         method
         operationId
         path
+        isMcpServer
       }
     }
     components {

package/src/lib/plugins/openapi/index.tsx

@@ -36,6 +36,7 @@ export const GetNavigationOperationsQuery = graphql(`
           method
           operationId
           path
+          isMcpServer
         }
       }
       components {

package/src/lib/plugins/openapi/mcp-configs.ts

@@ -187,8 +187,38 @@ export const getMcpServerName = (
   return (data?.name as string) ?? summary ?? "mcp-server";
 };
 
-export const getMcpUrl = (serverUrl?: string, operationPath?: string) =>
-  `${(serverUrl ?? "").replace(/\/+$/, "")}${operationPath ?? "/mcp"}`;
+// Matches a URL that carries its own scheme, e.g. `https://mcp.example.com`.
+const isAbsoluteUrl = (value: string) => /^[a-z][a-z0-9+.-]*:\/\//i.test(value);
+
+// Reads the `url` override from x-mcp-server, ignoring blank and non-string
+// values so callers fall back to the derived endpoint.
+const getUrlOverride = (data?: McpServerData): string | undefined => {
+  if (typeof data === "boolean") return undefined;
+
+  const url = data?.url;
+  if (typeof url !== "string") return undefined;
+
+  const trimmed = url.trim();
+  return trimmed === "" ? undefined : trimmed;
+};
+
+// The MCP endpoint is derived from the API's server URL plus the operation
+// path. An `x-mcp-server.url` override takes precedence, for servers that are
+// not hosted under the documented API server: an absolute URL replaces the
+// endpoint entirely, anything else is treated as a path on the server URL.
+export const getMcpUrl = (
+  serverUrl?: string,
+  operationPath?: string,
+  data?: McpServerData,
+) => {
+  const override = getUrlOverride(data);
+  if (override && isAbsoluteUrl(override)) return override;
+
+  const path = override ?? operationPath ?? "/mcp";
+  return `${(serverUrl ?? "").replace(/\/+$/, "")}${
+    path.startsWith("/") ? path : `/${path}`
+  }`;
+};
 
 export const getClaudeCodeCommand = (
   name: string,

package/src/lib/plugins/openapi/util/createNavigationCategory.tsx

@@ -29,11 +29,15 @@ export const createNavigationCategory = ({
     type: "link" as const,
     label: operation.summary ?? operation.path,
     to: `${path}#${operation.slug}`,
-    badge: {
-      label: operation.method,
-      // biome-ignore lint/style/noNonNullAssertion: is guaranteed to be defined
-      color: MethodColorMap[operation.method.toLowerCase()]!,
-      invert: true,
-    },
+    badge: operation.isMcpServer
+      ? // MCP server endpoints are reached over MCP, so the underlying HTTP
+        // method isn't meaningful to the reader.
+        { label: "MCP", color: "indigo" as const, invert: true }
+      : {
+          label: operation.method,
+          // biome-ignore lint/style/noNonNullAssertion: is guaranteed to be defined
+          color: MethodColorMap[operation.method.toLowerCase()]!,
+          invert: true,
+        },
   })),
 });

package/src/lib/plugins/search-inkeep/index.tsx

@@ -37,10 +37,12 @@ export type InkeepSearchPluginOptions = InkeepBaseSettings &
 
 const InkeepSearch = ({
   isOpen,
+  onOpen,
   onClose,
   settings,
 }: {
   isOpen: boolean;
+  onOpen: () => void;
   onClose: () => void;
   settings: InkeepSearchPluginOptions;
 }) => {
@@ -71,7 +73,16 @@ const InkeepSearch = ({
         ...modalSettings,
         onOpenChange: (newOpen: boolean) => {
           modalSettings?.onOpenChange?.(newOpen);
-          if (!newOpen) onClose();
+          // The modal is controlled through `isOpen`, so Inkeep never opens or
+          // closes itself: it only reports what it wants (Escape, a
+          // `triggerSelector` click, or a `shortcutKey` if one was configured).
+          // Both directions have to be mirrored back into Zudoku's state,
+          // otherwise those interactions do nothing at all.
+          if (newOpen) {
+            onOpen();
+          } else {
+            onClose();
+          }
         },
       },
       searchSettings: {
@@ -83,28 +94,44 @@ const InkeepSearch = ({
         ...aiChatSettings,
       },
     };
-  }, [onClose, settings]);
-  const [searchInstance, setSearchInstance] = useState<
-    InkeepComponentInstance | undefined
-  >(
-    typeof window !== "undefined" && window.Inkeep?.ModalSearchAndChat
-      ? window.Inkeep.ModalSearchAndChat(config)
-      : undefined,
-  );
+  }, [onClose, onOpen, settings]);
+
+  const [searchInstance, setSearchInstance] =
+    useState<InkeepComponentInstance>();
 
   useEffect(() => {
-    if (searchInstance) return;
+    let instance: InkeepComponentInstance | undefined;
+
+    // Every call mounts another widget into the DOM, so this must happen in an
+    // effect and never during render.
+    const createInstance = () => {
+      instance = window.Inkeep?.ModalSearchAndChat?.(config);
+      if (instance) setSearchInstance(instance);
+
+      return Boolean(instance);
+    };
+
+    const removeInstance = () => {
+      const created = instance;
+      if (!created) return;
+
+      instance = undefined;
+      // Defer so we never unmount synchronously mid-render (StrictMode).
+      setTimeout(() => created.unmount(), 0);
+    };
+
+    // The Inkeep script is loaded deferred, so poll until it is available
+    if (createInstance()) return removeInstance;
 
     const checkInkeep = setInterval(() => {
-      if (typeof window !== "undefined" && window.Inkeep?.ModalSearchAndChat) {
-        const inkeep = window.Inkeep.ModalSearchAndChat(config);
-        setSearchInstance(inkeep);
-        clearInterval(checkInkeep);
-      }
+      if (createInstance()) clearInterval(checkInkeep);
     }, 100);
 
-    return () => clearInterval(checkInkeep);
-  }, [config, searchInstance]);
+    return () => {
+      clearInterval(checkInkeep);
+      removeInstance();
+    };
+  }, [config]);
 
   useEffect(() => {
     if (!searchInstance) return;
@@ -128,10 +155,15 @@ export const inkeepSearchPlugin = (
         />
       );
     },
-    renderSearch: ({ isOpen, onClose }) => {
+    renderSearch: ({ isOpen, onOpen, onClose }) => {
       return (
         <ClientOnly>
-          <InkeepSearch isOpen={isOpen} onClose={onClose} settings={settings} />
+          <InkeepSearch
+            isOpen={isOpen}
+            onOpen={onOpen}
+            onClose={onClose}
+            settings={settings}
+          />
         </ClientOnly>
       );
     },

package/src/lib/plugins/search-inkeep/inkeep.ts

@@ -10,7 +10,11 @@ const baseSettings: InkeepBaseSettings = {
 };
 
 const modalSettings: InkeepModalSettings = {
-  shortcutKey: "k",
+  // Zudoku renders the search button and owns the ⌘K / Ctrl+K shortcut (see
+  // `Search.tsx`), so Inkeep's built-in one is disabled by default. Inkeep
+  // binds its shortcut on `document` and calls `stopPropagation()`, which
+  // swallows the event before it reaches Zudoku's listener on `window`.
+  shortcutKey: null,
 };
 
 const searchSettings: InkeepSearchSettings = {