diff --git a/docs/mcp-introduction.mdx b/docs/mcp-introduction.mdx
index a00f3dda89..e0e48b1054 100644
--- a/docs/mcp-introduction.mdx
+++ b/docs/mcp-introduction.mdx
@@ -220,7 +220,10 @@ Each client has a slightly different config format. Copy the snippet for your cl
     [mcp_servers.trigger]
     command = "npx"
     args = ["trigger.dev@latest", "mcp"]
+    startup_timeout_sec = 30
     ```
+
+    <Note>The `startup_timeout_sec = 30` is recommended. Codex defaults to 10 seconds, which may not be enough for `npx` to download the package on first run.</Note>
   </Tab>
   <Tab title="Crush">
     Install using the command line:
diff --git a/packages/cli-v3/src/commands/install-mcp.ts b/packages/cli-v3/src/commands/install-mcp.ts
index 545014292d..e1c9519e38 100644
--- a/packages/cli-v3/src/commands/install-mcp.ts
+++ b/packages/cli-v3/src/commands/install-mcp.ts
@@ -328,7 +328,7 @@ async function installMcpServerForClient(
   return { configPath, clientName, scope };
 }
 
-type McpServerConfig = Record<string, string | Array<string> | boolean | undefined>;
+type McpServerConfig = Record<string, string | Array<string> | boolean | number | undefined>;
 type McpServerScope = {
   scope: (typeof scopes)[number];
   location: string;
@@ -538,6 +538,7 @@ function resolveMcpServerConfig(
       return {
         command: "npx",
         args,
+        startup_timeout_sec: 30,
       };
     }
     case "zed": {