Add on-demand connection mode for ephemeral MCP servers

README.md

@@ -98,6 +98,34 @@ Manual registration example:
 
 For manual providers, create the OAuth App in the upstream console, set the redirect URI to `http://localhost:3000/oauth/callback` (or your deployed domain), and then plug the credentials into the dashboard or config file.
 
+#### Connection Modes (Optional)
+
+MCPHub supports two connection strategies:
+
+- **`persistent` (default)**: Maintains long-running connections for stateful servers
+- **`on-demand`**: Connects only when needed, ideal for ephemeral servers that exit after operations
+
+Example for one-time use servers:
+
+```json
+{
+  "mcpServers": {
+    "pdf-reader": {
+      "command": "npx",
+      "args": ["-y", "pdf-mcp-server"],
+      "connectionMode": "on-demand"
+    }
+  }
+}
+```
+
+Use `on-demand` mode for servers that:
+- Don't support long-running connections
+- Exit automatically after handling requests
+- Experience "Connection closed" errors
+
+See the [Configuration Guide](docs/configuration/mcp-settings.mdx) for more details.
+
 ### Docker Deployment
 
 **Recommended**: Mount your custom config:

docs/configuration/mcp-settings.mdx

@@ -72,9 +72,13 @@ MCPHub uses several configuration files:
 
 ### Optional Fields
 
-| Field          | Type    | Default         | Description                 |
-| -------------- | ------- | --------------- | --------------------------- |
-| `env`          | object  | `{}`            | Environment variables       |
+| Field            | Type    | Default         | Description                                                           |
+| ---------------- | ------- | --------------- | --------------------------------------------------------------------- |
+| `env`            | object  | `{}`            | Environment variables                                                 |
+| `connectionMode` | string  | `"persistent"`  | Connection strategy: `"persistent"` or `"on-demand"`                  |
+| `enabled`        | boolean | `true`          | Enable/disable the server                                             |
+| `keepAliveInterval` | number | `60000`      | Keep-alive ping interval for SSE connections (milliseconds)           |
+| `options`        | object  | `{}`            | MCP request options (timeout, resetTimeoutOnProgress, maxTotalTimeout)|
 
 ## Common MCP Server Examples
 
@@ -238,6 +242,68 @@ MCPHub uses several configuration files:
 }
 ```
 
+## Connection Modes
+
+MCPHub supports two connection strategies for MCP servers:
+
+### Persistent Connection (Default)
+
+Persistent mode maintains a long-running connection to the MCP server. This is the default and recommended mode for most servers.
+
+**Use cases:**
+- Servers that maintain state between requests
+- Servers with slow startup times
+- Servers designed for long-running connections
+
+**Example:**
+```json
+{
+  "github": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-github"],
+    "connectionMode": "persistent",
+    "env": {
+      "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
+    }
+  }
+}
+```
+
+### On-Demand Connection
+
+On-demand mode connects only when a tool is invoked, then disconnects immediately after. This is ideal for servers that:
+- Don't support long-running connections
+- Are designed for one-time use
+- Exit automatically after handling requests
+
+**Use cases:**
+- PDF processing tools that exit after each operation
+- One-time command-line utilities
+- Servers with connection stability issues
+- Resource-intensive servers that shouldn't run continuously
+
+**Example:**
+```json
+{
+  "pdf-reader": {
+    "command": "npx",
+    "args": ["-y", "pdf-mcp-server"],
+    "connectionMode": "on-demand",
+    "env": {
+      "PDF_CACHE_DIR": "/tmp/pdf-cache"
+    }
+  }
+}
+```
+
+**Benefits of on-demand mode:**
+- Avoids "Connection closed" errors for ephemeral services
+- Reduces resource usage for infrequently used tools
+- Better suited for stateless operations
+- Handles servers that automatically exit after operations
+
+**Note:** On-demand servers briefly connect during initialization to discover available tools, then disconnect. The connection is re-established only when a tool from that server is actually invoked.
+
 ## Advanced Configuration
 
 ### Environment Variable Substitution

examples/mcp_settings_with_connection_modes.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "description": "Example MCP settings showing different connection modes",
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "connectionMode": "persistent",
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
+      },
+      "enabled": true
+    },
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest", "--headless"],
+      "connectionMode": "persistent",
+      "enabled": true
+    },
+    "pdf-reader": {
+      "command": "npx",
+      "args": ["-y", "pdf-mcp-server"],
+      "connectionMode": "on-demand",
+      "env": {
+        "PDF_CACHE_DIR": "/tmp/pdf-cache"
+      },
+      "enabled": true
+    },
+    "image-processor": {
+      "command": "python",
+      "args": ["-m", "image_mcp_server"],
+      "connectionMode": "on-demand",
+      "env": {
+        "IMAGE_OUTPUT_DIR": "/tmp/images"
+      },
+      "enabled": true
+    },
+    "fetch": {
+      "command": "uvx",
+      "args": ["mcp-server-fetch"],
+      "enabled": true
+    },
+    "slack": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-slack"],
+      "connectionMode": "persistent",
+      "env": {
+        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
+        "SLACK_TEAM_ID": "${SLACK_TEAM_ID}"
+      },
+      "enabled": true
+    }
+  },
+  "users": [
+    {
+      "username": "admin",
+      "password": "$2b$10$Vt7krIvjNgyN67LXqly0uOcTpN0LI55cYRbcKC71pUDAP0nJ7RPa.",
+      "isAdmin": true
+    }
+  ]
+}