Merge pull request #109 from kernel/codex/api-keys-mcp-tool

Add MCP API key management tool

Author: IlyaasK

.env.example

@@ -17,6 +17,11 @@ API_BASE_URL=<x>
 MINTLIFY_ASSISTANT_API_TOKEN=mint_dsc_<x>
 MINTLIFY_DOMAIN=<x>
 
+# Optional MCP toolset gating. Comma-separated values.
+# Example: api_keys hides manage_api_keys so deployments can opt out of key management.
+# Supported: apps, api_keys, browser_pools, browsers, computer, docs, extensions, playwright, profiles, projects, proxies, shell
+# KERNEL_MCP_DISABLED_TOOLSETS=api_keys
+
 # Redis Configuration
 REDIS_URL=<x> # redis://127.0.0.1:6379
 # REDIS_TLS_SERVER_NAME=<x> # optional; requires REDIS_URL to use rediss://

README.md

@@ -255,10 +255,12 @@ Many other MCP-capable tools accept:
 
 Configure these values wherever the tool expects MCP server settings.
 
-## Tools (10 total)
+## Tools (12 total)
 
 Each Kernel feature has a single `manage_*` tool with an `action` parameter, keeping the tool set small and consistent. Four standalone tools handle high-frequency workflows.
 
+Self-hosted deployments can hide sensitive tool families by setting `KERNEL_MCP_DISABLED_TOOLSETS` to a comma-separated list. For example, `KERNEL_MCP_DISABLED_TOOLSETS=api_keys` prevents `manage_api_keys` from being registered.
+
 ### manage\_\* tools
 
 - `manage_browsers` - Create, list, get, and delete browser sessions. Supports headless/stealth modes, profiles, proxies, viewports, extensions, and SSH tunneling.
@@ -267,6 +269,8 @@ Each Kernel feature has a single `manage_*` tool with an `action` parameter, kee
 - `manage_proxies` - Create, list, and delete proxy configurations (datacenter, ISP, residential, mobile, custom).
 - `manage_extensions` - List and delete uploaded browser extensions.
 - `manage_apps` - List apps, invoke actions, get/list deployments, and get invocation results.
+- `manage_projects` - Create, list, get, update, and delete organization projects.
+- `manage_api_keys` - Create, list, get, update, and delete Kernel API keys. Create returns the plaintext key once.
 
 ### Standalone tools
 

src/lib/mcp/register.ts

@@ -1,5 +1,6 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { registerKernelPrompts } from "@/lib/mcp/prompts";
+import { registerAPIKeyCapabilities } from "@/lib/mcp/tools/api-keys";
 import { registerAppCapabilities } from "@/lib/mcp/tools/apps";
 import { registerBrowserPoolCapabilities } from "@/lib/mcp/tools/browser-pools";
 import { registerBrowserCapabilities } from "@/lib/mcp/tools/browsers";
@@ -12,17 +13,107 @@ import { registerProjectCapabilities } from "@/lib/mcp/tools/projects";
 import { registerProxyTools } from "@/lib/mcp/tools/proxies";
 import { registerShellTool } from "@/lib/mcp/tools/shell";
 
+type RegisterMcpToolset = (server: McpServer) => void;
+
+const mcpToolRegistrations = [
+  ["profiles", registerProfileCapabilities],
+  ["docs", registerDocsTools],
+  ["browsers", registerBrowserCapabilities],
+  ["projects", registerProjectCapabilities],
+  ["api_keys", registerAPIKeyCapabilities],
+  ["browser_pools", registerBrowserPoolCapabilities],
+  ["proxies", registerProxyTools],
+  ["extensions", registerExtensionTools],
+  ["apps", registerAppCapabilities],
+  ["computer", registerComputerActionTool],
+  ["shell", registerShellTool],
+  ["playwright", registerPlaywrightTool],
+] as const satisfies readonly (readonly [string, RegisterMcpToolset])[];
+
+type McpToolset = (typeof mcpToolRegistrations)[number][0];
+
+const mcpToolsets = mcpToolRegistrations.map(([toolset]) => toolset);
+const mcpToolsetSet: ReadonlySet<string> = new Set(mcpToolsets);
+
+const standaloneToolsetAliases: Partial<Record<string, McpToolset>> = {
+  computer_action: "computer",
+  search_docs: "docs",
+  execute_playwright_code: "playwright",
+  exec_command: "shell",
+};
+
+function isMcpToolset(value: string): value is McpToolset {
+  return mcpToolsetSet.has(value);
+}
+
+function resolveMcpToolset(token: string): McpToolset | undefined {
+  if (isMcpToolset(token)) return token;
+  return standaloneToolsetAliases[token];
+}
+
+function normalizeMcpToolset(value: string): McpToolset | undefined {
+  const token = value.trim().toLowerCase().replace(/-/g, "_");
+  const toolset = resolveMcpToolset(token);
+  if (toolset) return toolset;
+
+  const managePrefix = "manage_";
+  if (token.startsWith(managePrefix)) {
+    return resolveMcpToolset(token.slice(managePrefix.length));
+  }
+
+  return undefined;
+}
+
+function disabledMcpToolsetsFromEnv() {
+  const raw = process.env.KERNEL_MCP_DISABLED_TOOLSETS;
+  if (!raw?.trim()) return new Set<McpToolset>();
+
+  const disabled = new Set<McpToolset>();
+  let disableAll = false;
+  const unknown: string[] = [];
+
+  for (const value of raw.split(/[,\s]+/)) {
+    const token = value.trim().toLowerCase();
+    if (!token || token === "none") continue;
+    if (token === "all") {
+      disableAll = true;
+      continue;
+    }
+
+    const toolset = normalizeMcpToolset(token);
+    if (toolset) {
+      disabled.add(toolset);
+    } else {
+      unknown.push(value);
+    }
+  }
+
+  if (unknown.length > 0) {
+    throw new Error(
+      `Unknown KERNEL_MCP_DISABLED_TOOLSETS value(s): ${unknown.join(", ")}. Supported toolsets: ${mcpToolsets.join(", ")}.`,
+    );
+  }
+
+  if (disableAll) return new Set<McpToolset>(mcpToolsets);
+
+  return disabled;
+}
+
+function toolsetEnabled(
+  disabledToolsets: Set<McpToolset>,
+  toolset: McpToolset,
+) {
+  return !disabledToolsets.has(toolset);
+}
+
 export function registerMcpCapabilities(server: McpServer) {
-  registerProfileCapabilities(server);
+  const disabledToolsets = disabledMcpToolsetsFromEnv();
+
   registerKernelPrompts(server);
-  registerDocsTools(server);
-  registerBrowserCapabilities(server);
-  registerProjectCapabilities(server);
-  registerBrowserPoolCapabilities(server);
-  registerProxyTools(server);
-  registerExtensionTools(server);
-  registerAppCapabilities(server);
-  registerComputerActionTool(server);
-  registerShellTool(server);
-  registerPlaywrightTool(server);
+
+  for (const [toolset, registerToolset] of mcpToolRegistrations) {
+    if (toolsetEnabled(disabledToolsets, toolset)) {
+      registerToolset(server);
+    }
+  }
 }

src/lib/mcp/responses.ts

@@ -0,0 +1,39 @@
+type PaginatedPage<T> = {
+  getPaginatedItems(): T[];
+  has_more?: boolean | null;
+  next_offset?: number | null;
+};
+
+export function textResponse(text: string) {
+  return { content: [{ type: "text" as const, text }] };
+}
+
+export function jsonResponse(value: unknown) {
+  return textResponse(JSON.stringify(value, null, 2) ?? String(value));
+}
+
+export function paginatedJsonResponse<T>(page: PaginatedPage<T>) {
+  return jsonResponse({
+    items: page.getPaginatedItems(),
+    has_more: page.has_more,
+    next_offset: page.next_offset,
+  });
+}
+
+export function errorResponse(text: string) {
+  return { ...textResponse(text), isError: true as const };
+}
+
+function errorMessage(error: unknown) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export function toolErrorResponse(
+  toolName: string,
+  action: string,
+  error: unknown,
+) {
+  return errorResponse(
+    `Error in ${toolName} (${action}): ${errorMessage(error)}`,
+  );
+}

src/lib/mcp/schemas.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+
+export const paginationParams = {
+  limit: z
+    .number()
+    .int()
+    .describe(
+      "(list) Max results per page. Defaults to 20; API clamps to 1-100.",
+    )
+    .optional(),
+  offset: z
+    .number()
+    .int()
+    .describe(
+      "(list) Pagination offset. Defaults to 0; API clamps negatives to 0.",
+    )
+    .optional(),
+};

src/lib/mcp/tools/api-keys.ts

@@ -0,0 +1,114 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { createKernelClient } from "@/lib/mcp/kernel-client";
+import {
+  errorResponse,
+  jsonResponse,
+  paginatedJsonResponse,
+  textResponse,
+  toolErrorResponse,
+} from "@/lib/mcp/responses";
+import { paginationParams } from "@/lib/mcp/schemas";
+
+export function registerAPIKeyCapabilities(server: McpServer) {
+  // manage_api_keys -- Create, list, get, update, and delete Kernel API keys
+  server.tool(
+    "manage_api_keys",
+    'Manage Kernel API keys. Use "create" to create an org-wide or project-scoped key, "list" to discover masked keys, "get" to retrieve one masked key, "update" to rename a key, or "delete" to revoke a key. Created keys include the plaintext key once.',
+    {
+      action: z
+        .enum(["create", "list", "get", "update", "delete"])
+        .describe("Operation to perform."),
+      api_key_id: z
+        .string()
+        .describe("API key ID. Required for get, update, and delete.")
+        .optional(),
+      name: z.string().describe("(create, update) API key name.").optional(),
+      project_id: z
+        .string()
+        .nullable()
+        .describe(
+          "(create) Project ID for project-scoped keys. Omit or use null for org-wide keys.",
+        )
+        .optional(),
+      days_to_expire: z
+        .number()
+        .int()
+        .min(1)
+        .max(3650)
+        .nullable()
+        .describe(
+          "(create) Days until expiry, up to 3650. Use null for no expiry.",
+        )
+        .optional(),
+      ...paginationParams,
+    },
+    {
+      title: "Manage Kernel API keys",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: false,
+    },
+    async (params, extra) => {
+      if (!extra.authInfo) throw new Error("Authentication required");
+      const client = createKernelClient(extra.authInfo.token);
+
+      try {
+        switch (params.action) {
+          case "create": {
+            if (!params.name) {
+              return errorResponse("Error: name is required for create.");
+            }
+            const createParams: Parameters<typeof client.apiKeys.create>[0] = {
+              name: params.name,
+            };
+            if (params.project_id !== undefined) {
+              createParams.project_id = params.project_id;
+            }
+            if (params.days_to_expire !== undefined) {
+              createParams.days_to_expire = params.days_to_expire;
+            }
+            const apiKey = await client.apiKeys.create(createParams);
+            return jsonResponse(apiKey);
+          }
+          case "list": {
+            const page = await client.apiKeys.list({
+              ...(params.limit !== undefined && { limit: params.limit }),
+              ...(params.offset !== undefined && { offset: params.offset }),
+            });
+            return paginatedJsonResponse(page);
+          }
+          case "get": {
+            if (!params.api_key_id) {
+              return errorResponse("Error: api_key_id is required for get.");
+            }
+            const apiKey = await client.apiKeys.retrieve(params.api_key_id);
+            return jsonResponse(apiKey);
+          }
+          case "update": {
+            if (!params.api_key_id) {
+              return errorResponse("Error: api_key_id is required for update.");
+            }
+            if (!params.name) {
+              return errorResponse("Error: name is required for update.");
+            }
+            const apiKey = await client.apiKeys.update(params.api_key_id, {
+              name: params.name,
+            });
+            return jsonResponse(apiKey);
+          }
+          case "delete": {
+            if (!params.api_key_id) {
+              return errorResponse("Error: api_key_id is required for delete.");
+            }
+            await client.apiKeys.delete(params.api_key_id);
+            return textResponse("API key deleted successfully");
+          }
+        }
+      } catch (error) {
+        return toolErrorResponse("manage_api_keys", params.action, error);
+      }
+    },
+  );
+}