portkey-admin-mcp 0.8.0 → 0.10.0

package/README.md

@@ -15,6 +15,8 @@
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
   <br>
   <a href="https://github.com/CodesWhat/portkey-admin-mcp/actions/workflows/ci.yml"><img src="https://github.com/CodesWhat/portkey-admin-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://securityscorecards.dev/viewer/?uri=github.com/CodesWhat/portkey-admin-mcp"><img src="https://img.shields.io/ossf-scorecard/github.com/CodesWhat/portkey-admin-mcp?label=openssf+scorecard&style=flat" alt="OpenSSF Scorecard"></a>
+  <a href="https://www.bestpractices.dev/projects/14031"><img src="https://www.bestpractices.dev/projects/14031/badge" alt="OpenSSF Best Practices"></a>
   <a href="https://github.com/punkpeye/awesome-mcp-servers"><img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome MCP Servers"></a>
   <a href="https://lobehub.com/mcp/codeswhat-portkey-admin-mcp"><img src="https://lobehub.com/badge/mcp/codeswhat-portkey-admin-mcp" alt="LobeHub MCP"></a>
 </p>
@@ -34,8 +36,13 @@
 - [🧰 What You Can Do](#what-you-can-do)
 - [🔑 API Key Scopes](#api-key-scopes)
 - [🌐 HTTP Server (Experimental)](#http-server)
+- [🏗️ Architecture](./docs/ARCHITECTURE.md)
 - [🔄 Prisma AIRS interoperability](./docs/PRISMA_AIRS_INTEROPERABILITY.md)
+- [🔏 Verify a release](./docs/VERIFY_RELEASE.md)
 - [🛠️ Development](#development)
+- [🤝 Contributing](./CONTRIBUTING.md)
+- [🏛️ Governance](./GOVERNANCE.md)
+- [🛡️ Security assurance](./SECURITY-ASSURANCE.md)
 - [🧾 Full tool list — ENDPOINTS.md](./ENDPOINTS.md)
 
 <hr>
@@ -219,6 +226,7 @@ For local-only HTTP use, leave `MCP_HOST` at its default `127.0.0.1`. Set `MCP_H
 | `MCP_MAX_SESSIONS` | `100` | Maximum concurrent stateful sessions or active stateless request handlers |
 | `MCP_EVENT_STORE` | `off` | `off`, `memory`, or `redis`; stateless `GET /mcp` replay requires `memory` or `redis` |
 | `MCP_EVENT_TTL_SECONDS` | `300` | Replay retention in seconds |
+| `MCP_EVENT_STORE_COMMAND_TIMEOUT_MS` | `5000` | Redis command timeout for the event store, in milliseconds; `0` disables the timeout (restores unbounded pre-v6 behavior) |
 | `MCP_REDIS_URL` | — | Redis URL for shared event store; production requires `rediss://` and ACL-scoped credentials |
 | `MCP_EVENT_ENCRYPTION_KEY` | — | Required 32-byte base64 AES key for Redis replay payloads; generate with `openssl rand -base64 32` |
 | `MCP_REDIS_KEY_PREFIX` | `mcp:event-store` | Dedicated Redis namespace for replay data |
@@ -283,13 +291,24 @@ docker run \
 npm run dev           # stdio with hot reload
 npm run dev:http      # HTTP with hot reload
 npm test              # unit + contract tests
+npm run test:coverage # unit + contract tests with the enforced 80% line floor
 npm run test:e2e      # MCP protocol tests
 npm run test:http     # HTTP endpoint smoke test
-npm run ci            # full pipeline (lint + typecheck + test + build + e2e + verify)
+npm run ci            # full pipeline (lint + typecheck + coverage + build + e2e + verify)
 ```
 
+The required CI and release gates measure every TypeScript source file and fail
+below 80% line coverage. The current full report is 99.36% lines, 92.61%
+branches, and 99.01% functions.
+
 `npm run dev:http` now requires `MCP_AUTH_MODE=bearer` or `MCP_AUTH_MODE=clerk` by default. For deliberate local-only unauthenticated testing, set `MCP_ALLOW_UNAUTHENTICATED_HTTP=true`.
 
+Contributions use pull requests and the checks documented in
+[`CONTRIBUTING.md`](CONTRIBUTING.md). Project decisions and maintainer roles are
+documented in [`GOVERNANCE.md`](GOVERNANCE.md). Report vulnerabilities through
+[`SECURITY.md`](SECURITY.md), and see [`SECURITY-ASSURANCE.md`](SECURITY-ASSURANCE.md)
+for the public threat model and assurance case.
+
 ---
 
 <div align="center">

package/build/index.js

@@ -3,6 +3,59 @@
 // src/index.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
+// src/lib/logger.ts
+var LOG_LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
+function getConfiguredLogLevel() {
+  const envLevel = process.env.LOG_LEVEL?.toLowerCase();
+  if (envLevel && envLevel in LOG_LEVELS) {
+    return envLevel;
+  }
+  return "info";
+}
+var configuredLogLevel = getConfiguredLogLevel();
+function shouldLog(level) {
+  return LOG_LEVELS[level] >= LOG_LEVELS[configuredLogLevel];
+}
+function formatEntry(level, message, extra) {
+  return {
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    level,
+    message,
+    ...extra
+  };
+}
+function writeLog(entry) {
+  process.stderr.write(`${JSON.stringify(entry)}
+`);
+}
+var Logger = {
+  debug(message, extra) {
+    if (shouldLog("debug")) {
+      writeLog(formatEntry("debug", message, extra));
+    }
+  },
+  info(message, extra) {
+    if (shouldLog("info")) {
+      writeLog(formatEntry("info", message, extra));
+    }
+  },
+  warn(message, extra) {
+    if (shouldLog("warn")) {
+      writeLog(formatEntry("warn", message, extra));
+    }
+  },
+  error(message, extra) {
+    if (shouldLog("error")) {
+      writeLog(formatEntry("error", message, extra));
+    }
+  }
+};
+
 // src/lib/mcp-server.ts
 import { readFileSync } from "node:fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -64,62 +117,10 @@ async function parseErrorResponse(response) {
   }
 }
 
-// src/lib/logger.ts
-var LOG_LEVELS = {
-  debug: 0,
-  info: 1,
-  warn: 2,
-  error: 3
-};
-function getConfiguredLogLevel() {
-  const envLevel = process.env.LOG_LEVEL?.toLowerCase();
-  if (envLevel && envLevel in LOG_LEVELS) {
-    return envLevel;
-  }
-  return "info";
-}
-var configuredLogLevel = getConfiguredLogLevel();
-function shouldLog(level) {
-  return LOG_LEVELS[level] >= LOG_LEVELS[configuredLogLevel];
-}
-function formatEntry(level, message, extra) {
-  return {
-    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-    level,
-    message,
-    ...extra
-  };
-}
-function writeLog(entry) {
-  process.stderr.write(`${JSON.stringify(entry)}
-`);
-}
-var Logger = {
-  debug(message, extra) {
-    if (shouldLog("debug")) {
-      writeLog(formatEntry("debug", message, extra));
-    }
-  },
-  info(message, extra) {
-    if (shouldLog("info")) {
-      writeLog(formatEntry("info", message, extra));
-    }
-  },
-  warn(message, extra) {
-    if (shouldLog("warn")) {
-      writeLog(formatEntry("warn", message, extra));
-    }
-  },
-  error(message, extra) {
-    if (shouldLog("error")) {
-      writeLog(formatEntry("error", message, extra));
-    }
-  }
-};
-
 // src/services/base.service.ts
 var DEFAULT_BASE_URL = "https://api.portkey.ai/v1";
 var DEFAULT_PUBLIC_BASE_URL = "https://api.portkey.ai";
+var MISSING_API_KEY_PLACEHOLDER = "__PORTKEY_API_KEY_NOT_CONFIGURED__";
 var PRIVATE_BASE_URL_OVERRIDE_HINT = "Set PORTKEY_ALLOW_PRIVATE_BASE_URL=true to allow self-hosted gateways on loopback or private networks.";
 var INSECURE_HTTP_OVERRIDE_HINT = "Set PORTKEY_ALLOW_INSECURE_HTTP=true only for a trusted self-hosted gateway when TLS is unavailable.";
 function isPrivateOrLocalHost(hostname) {
@@ -233,6 +234,11 @@ var BaseService = class {
     return body ? JSON.stringify(body) : void 0;
   }
   async executeRequest(method, path, options = {}) {
+    if ((options.authenticate ?? true) && this.apiKey === MISSING_API_KEY_PLACEHOLDER) {
+      throw new Error(
+        "PORTKEY_API_KEY is not configured. Set the PORTKEY_API_KEY environment variable to a valid Portkey Admin API key."
+      );
+    }
     const requestId = crypto.randomUUID();
     const url = this.buildUrl(path, options.params, options.baseUrl);
     const startTime = Date.now();
@@ -1795,7 +1801,6 @@ var WorkspacesService = class extends BaseService {
 
 // src/services/index.ts
 import { createHmac, randomBytes } from "node:crypto";
-var MISSING_API_KEY_PLACEHOLDER = "__PORTKEY_API_KEY_NOT_CONFIGURED__";
 var SERVICE_CACHE_HMAC_KEY = randomBytes(32);
 function resolvePortkeyApiKey(apiKey) {
   const resolvedApiKey = apiKey ?? process.env.PORTKEY_API_KEY;
@@ -2684,6 +2689,14 @@ function buildConfigPayload(params) {
 function hasConfigSettings(config) {
   return config.cache !== void 0 || config.retry !== void 0 || config.strategy !== void 0 || config.targets !== void 0;
 }
+var createConfigSchema = z5.object(CONFIGS_TOOL_SCHEMAS.createConfig).superRefine((value, ctx) => {
+  if (!hasConfigSettings(buildConfigPayload(value))) {
+    ctx.addIssue({
+      code: z5.ZodIssueCode.custom,
+      message: "At least one config setting (cache_mode, retry_attempts, strategy_mode, or targets) must be provided"
+    });
+  }
+});
 function registerConfigsTools(server, service) {
   server.tool(
     "list_configs",
@@ -2749,25 +2762,15 @@ function registerConfigsTools(server, service) {
     "Create a config that defines routing, cache, retry, and targets for requests; use update_config to modify an existing one and list_config_versions for history. At least one setting is required, new configs become active immediately once referenced by a key or prompt, and the call returns the new id and version_id.",
     CONFIGS_TOOL_SCHEMAS.createConfig,
     async (params) => {
-      const config = buildConfigPayload(params);
-      if (!hasConfigSettings(config)) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: "Error creating configuration: At least one config setting (cache_mode, retry_attempts, strategy_mode, or targets) must be provided"
-            }
-          ],
-          isError: true
-        };
-      }
+      const validated = createConfigSchema.parse(params);
+      const config = buildConfigPayload(validated);
       const result = await service.configs.createConfig({
-        name: params.name,
+        name: validated.name,
         config,
-        workspace_id: params.workspace_id
+        workspace_id: validated.workspace_id
       });
       return jsonResult({
-        message: `Successfully created configuration "${params.name}"`,
+        message: `Successfully created configuration "${validated.name}"`,
         id: result.id,
         version_id: result.version_id
       });
@@ -3396,6 +3399,16 @@ var INTEGRATIONS_TOOL_SCHEMAS = {
     default_provider_slug: z8.string().optional().describe("Default slug for providers auto-created in workspaces")
   }
 };
+var updateIntegrationWorkspacesSchema = z8.object(INTEGRATIONS_TOOL_SCHEMAS.updateIntegrationWorkspaces).superRefine((value, ctx) => {
+  const hasGlobalLimits = value.global_credit_limit !== void 0 || value.global_alert_threshold !== void 0 || value.global_rate_limit_rpm !== void 0;
+  if (hasGlobalLimits && value.global_workspace_access_enabled === void 0) {
+    ctx.addIssue({
+      code: z8.ZodIssueCode.custom,
+      path: ["global_workspace_access_enabled"],
+      message: "global_workspace_access_enabled is required when setting global limits."
+    });
+  }
+});
 function buildIntegrationConfigurations(params) {
   const configurations = {};
   if (params.api_version !== void 0)
@@ -3673,19 +3686,8 @@ function registerIntegrationsTools(server, service) {
       idempotentHint: true,
       openWorldHint: true
     },
-    async (params) => {
-      const hasGlobalLimits = params.global_credit_limit !== void 0 || params.global_alert_threshold !== void 0 || params.global_rate_limit_rpm !== void 0;
-      if (hasGlobalLimits && params.global_workspace_access_enabled === void 0) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: "global_workspace_access_enabled is required when setting global limits."
-            }
-          ],
-          isError: true
-        };
-      }
+    async (rawParams) => {
+      const params = updateIntegrationWorkspacesSchema.parse(rawParams);
       const globalUsageLimits = params.global_credit_limit !== void 0 || params.global_alert_threshold !== void 0 ? [
         {
           type: "cost",
@@ -4163,23 +4165,21 @@ var LABELS_TOOL_SCHEMAS = {
     label_id: z10.string().describe("Label ID to delete")
   }
 };
+var createPromptLabelSchema = z10.object(LABELS_TOOL_SCHEMAS.createPromptLabel).superRefine((value, ctx) => {
+  if (!value.organisation_id && !value.workspace_id) {
+    ctx.addIssue({
+      code: z10.ZodIssueCode.custom,
+      message: "Either organisation_id or workspace_id is required"
+    });
+  }
+});
 function registerLabelsTools(server, service) {
   server.tool(
     "create_prompt_label",
     "Create a prompt label for tagging prompt versions such as production, staging, or experiment. Requires either organisation_id or workspace_id to set scope, returns the new label id, and does not assign it to any versions yet.",
     LABELS_TOOL_SCHEMAS.createPromptLabel,
-    async (params) => {
-      if (!params.organisation_id && !params.workspace_id) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: "Error: Either organisation_id or workspace_id is required"
-            }
-          ],
-          isError: true
-        };
-      }
+    async (rawParams) => {
+      const params = createPromptLabelSchema.parse(rawParams);
       const result = await service.labels.createLabel({
         name: params.name,
         organisation_id: params.organisation_id,
@@ -4589,12 +4589,13 @@ var logExportFieldSchema = z12.enum([
   "prompt_slug",
   "metadata"
 ]);
-var getLogInputSchema = z12.object({
+var getLogShape = {
   log_id: z12.string().describe("Gateway log ID to retrieve"),
   path_format: z12.enum(["v1", "v2"]).optional().describe("Log storage path format; defaults to v1"),
   created_at: z12.iso.datetime({ offset: true }).optional().describe("Log creation timestamp in ISO 8601 format; required for v2"),
   type: z12.enum(["hooks"]).optional().describe("Set to hooks when retrieving a hook execution log")
-}).superRefine((input, context) => {
+};
+var getLogSchema = z12.object(getLogShape).superRefine((input, context) => {
   if (input.path_format === "v2" && input.created_at === void 0) {
     context.addIssue({
       code: "custom",
@@ -4675,7 +4676,7 @@ function registerLoggingTools(server, service) {
     "get_log",
     {
       description: "Get one gateway request log by ID, including its request, response, usage, cost, and metadata payload when available. For path_format v2, also provide the log's created_at timestamp.",
-      inputSchema: getLogInputSchema,
+      inputSchema: getLogShape,
       annotations: {
         title: "Get Gateway Log",
         readOnlyHint: true,
@@ -4684,7 +4685,8 @@ function registerLoggingTools(server, service) {
         openWorldHint: true
       }
     },
-    async (params) => {
+    async (rawParams) => {
+      const params = getLogSchema.parse(rawParams);
       const result = await service.logging.getLog(params.log_id, {
         path_format: params.path_format,
         created_at: params.created_at,
@@ -4976,6 +4978,17 @@ var MCP_INTEGRATIONS_TOOL_SCHEMAS = {
     ).min(1).describe("Array of workspace access updates")
   }
 };
+var createMcpIntegrationSchema = z13.object(MCP_INTEGRATIONS_TOOL_SCHEMAS.createMcpIntegration).superRefine((value, ctx) => {
+  if (value.auth_type === "headers" && (!value.custom_headers || Object.keys(value.custom_headers).length === 0) && !value.secret_mappings?.some(
+    (mapping) => mapping.target_field === "configurations.custom_headers"
+  )) {
+    ctx.addIssue({
+      code: z13.ZodIssueCode.custom,
+      path: ["custom_headers"],
+      message: "custom_headers must be provided when auth_type is 'headers'"
+    });
+  }
+});
 function isRecord2(value) {
   return typeof value === "object" && value !== null;
 }
@@ -5054,20 +5067,8 @@ function registerMcpIntegrationsTools(server, service) {
       idempotentHint: false,
       openWorldHint: true
     },
-    async (params) => {
-      if (params.auth_type === "headers" && (!params.custom_headers || Object.keys(params.custom_headers).length === 0) && !params.secret_mappings?.some(
-        (mapping) => mapping.target_field === "configurations.custom_headers"
-      )) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: "Error: custom_headers must be provided when auth_type is 'headers'"
-            }
-          ],
-          isError: true
-        };
-      }
+    async (rawParams) => {
+      const params = createMcpIntegrationSchema.parse(rawParams);
       const { custom_headers, ...rest } = params;
       const result = await service.mcpIntegrations.createMcpIntegration({
         ...rest,
@@ -5904,6 +5905,28 @@ var PROMPTS_TOOL_SCHEMAS = {
     )
   }
 };
+var createPromptSchema = z17.object(PROMPTS_TOOL_SCHEMAS.createPrompt).superRefine((value, ctx) => {
+  if (!value.model && !value.ai_model_id && !value.finetune_id) {
+    ctx.addIssue({
+      code: z17.ZodIssueCode.custom,
+      message: "At least one of model, ai_model_id, or finetune_id must be provided"
+    });
+  }
+  if (value.string === void 0 && value.messages === void 0) {
+    ctx.addIssue({
+      code: z17.ZodIssueCode.custom,
+      message: "Provide either string or messages"
+    });
+  }
+});
+var migratePromptSchema = z17.object(PROMPTS_TOOL_SCHEMAS.migratePrompt).superRefine((value, ctx) => {
+  if (value.string === void 0 && value.messages === void 0) {
+    ctx.addIssue({
+      code: z17.ZodIssueCode.custom,
+      message: "Provide either string or messages"
+    });
+  }
+});
 function normalizePromptTemplateString(params) {
   if (params.string !== void 0) {
     return params.string;
@@ -5978,30 +6001,9 @@ function registerPromptsTools(server, service) {
     "create_prompt",
     "Create a new prompt template and initial version. Use this for first-time setup; use migrate_prompt for idempotent CI/CD flows. Accepts plain text or structured chat messages, creates a new version immediately, and returns the prompt id, slug, and version id. For multi-message chat prompts pass messages (preferred) or a JSON-encoded array as string.",
     PROMPTS_TOOL_SCHEMAS.createPrompt,
-    async (params) => {
-      if (!params.model && !params.ai_model_id && !params.finetune_id) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: "Error creating prompt: At least one of model, ai_model_id, or finetune_id must be provided"
-            }
-          ],
-          isError: true
-        };
-      }
+    async (rawParams) => {
+      const params = createPromptSchema.parse(rawParams);
       const templateString = normalizePromptTemplateString(params);
-      if (templateString === void 0) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: "Error creating prompt: Provide either string or messages"
-            }
-          ],
-          isError: true
-        };
-      }
       if (params.dry_run) {
         return jsonResult({
           dry_run: true,
@@ -6111,14 +6113,18 @@ function registerPromptsTools(server, service) {
       });
       if (dry_run) {
         const current = await service.prompts.getPrompt(prompt_id);
+        const changes = Object.keys(updateData).filter(
+          (k) => updateData[k] !== void 0
+        );
+        if (messages !== void 0 && !changes.includes("string")) {
+          changes.push("string");
+        }
         return jsonResult({
           dry_run: true,
           action: "update",
           message: `Would update prompt "${current.name}"`,
           current_version: current.current_version?.version_number ?? null,
-          changes: Object.keys(updateData).filter(
-            (k) => updateData[k] !== void 0
-          )
+          changes
         });
       }
       const result = await service.prompts.updatePrompt(prompt_id, {
@@ -6256,19 +6262,9 @@ function registerPromptsTools(server, service) {
       idempotentHint: true,
       openWorldHint: false
     },
-    async (params) => {
+    async (rawParams) => {
+      const params = migratePromptSchema.parse(rawParams);
       const templateString = normalizePromptTemplateString(params);
-      if (templateString === void 0) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: "Error migrating prompt: Provide either string or messages"
-            }
-          ],
-          isError: true
-        };
-      }
       const result = await service.prompts.migratePrompt({
         name: params.name,
         app: params.app,
@@ -7234,7 +7230,7 @@ var scimWorkspaceMappingBaseShape = {
   workspace_id: z22.string().describe("Portkey workspace ID that the SCIM group should access"),
   role: z22.enum(["admin", "member", "manager"]).describe("Workspace role automatically granted to group members")
 };
-var createScimWorkspaceMappingInputSchema = z22.object({
+var createScimWorkspaceMappingShape = {
   ...scimWorkspaceMappingBaseShape,
   scim_group_id: z22.string().min(1).optional().describe(
     "Existing identity-provider SCIM group ID; provide this or scim_group_name, but not both"
@@ -7242,7 +7238,8 @@ var createScimWorkspaceMappingInputSchema = z22.object({
   scim_group_name: z22.string().min(1).optional().describe(
     "Existing SCIM group display name; provide this or scim_group_id, but not both"
   )
-}).superRefine((input, context) => {
+};
+var createScimWorkspaceMappingSchema = z22.object(createScimWorkspaceMappingShape).superRefine((input, context) => {
   if (Boolean(input.scim_group_id) === Boolean(input.scim_group_name)) {
     context.addIssue({
       code: "custom",
@@ -7397,7 +7394,7 @@ function registerWorkspacesTools(server, service) {
     "create_scim_workspace_mapping",
     {
       description: "Map one identity-provider SCIM group to a Portkey workspace role so current and future group members receive access automatically. Provide exactly one of scim_group_id or scim_group_name; a name can pre-create the Portkey SCIM group before the IdP provisions it. Use list_scim_groups to discover existing groups and list_workspaces for the workspace ID. This changes access provisioning and is distinct from add_workspace_member, which grants one user directly.",
-      inputSchema: createScimWorkspaceMappingInputSchema,
+      inputSchema: createScimWorkspaceMappingShape,
       annotations: {
         title: "Create SCIM Workspace Mapping",
         readOnlyHint: false,
@@ -7406,7 +7403,8 @@ function registerWorkspacesTools(server, service) {
         openWorldHint: true
       }
     },
-    async (params) => {
+    async (rawParams) => {
+      const params = createScimWorkspaceMappingSchema.parse(rawParams);
       let request;
       if (params.scim_group_id !== void 0) {
         request = {
@@ -7767,7 +7765,25 @@ function augmentToolDescription(toolName, description) {
   }
   return `${description} ${ENTERPRISE_GATED_DESCRIPTION_NOTE}`;
 }
+function formatZodIssues(error) {
+  return error.issues.map((issue) => {
+    const path = issue.path.join(".");
+    if (!path) {
+      return issue.message;
+    }
+    const namesPath = new RegExp(`\\b${escapeRegExp(path)}\\b`).test(
+      issue.message
+    );
+    return namesPath ? issue.message : `${path}: ${issue.message}`;
+  }).join("; ");
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 function getToolErrorMessage(error) {
+  if (error instanceof z23.ZodError) {
+    return formatZodIssues(error);
+  }
   if (error instanceof Error && error.message) {
     return error.message;
   }
@@ -7914,14 +7930,14 @@ function wrapToolCallback(toolName, callback) {
       return normalizeToolResult(await callback(...args));
     } catch (error) {
       const message = getToolErrorMessage(error);
+      const isValidationError = error instanceof z23.ZodError;
+      const text = isValidationError ? `Invalid arguments for "${toolName}": ${message}` : `Tool "${toolName}" failed: ${message}`;
       Logger.error("Tool callback failed", {
         error: message,
         metadata: { toolName }
       });
       return normalizeToolResult({
-        content: [
-          { type: "text", text: `Tool "${toolName}" failed: ${message}` }
-        ],
+        content: [{ type: "text", text }],
         isError: true
       });
     }
@@ -8233,6 +8249,11 @@ function createMcpServer(options = {}) {
 // src/index.ts
 async function main() {
   try {
+    if (!process.env.PORTKEY_API_KEY) {
+      Logger.warn(
+        "PORTKEY_API_KEY is not set; tool calls will fail until it is configured."
+      );
+    }
     const { server } = createMcpServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);