feat(mcp): add --database-url CLI option for direct Redis connections

Add support for connecting to Redis databases via URL without requiring
a profile. This is useful for ad-hoc connections to standalone Redis
instances that aren't configured as profiles.

Changes:
- Add --database-url option to 'mcp serve' command (supports REDIS_URL env)
- Add DatabaseTools::new_from_url() constructor for URL-based connections
- Update get_database_tools() to prefer URL over profile when both available
- Update MCP documentation with both connection approaches
- Add unit test for database_url configuration

The URL format follows the standard Redis URL scheme:
redis[s]://[[username:]password@]host[:port][/db]

Author: joshrotenberg

crates/redisctl-mcp/src/database_tools.rs

@@ -63,6 +63,21 @@ impl DatabaseTools {
         Ok(Self { conn })
     }
 
+    /// Create a new DatabaseTools instance from a direct Redis URL.
+    ///
+    /// URL format: redis[s]://[[username:]password@]host[:port][/db]
+    ///
+    /// This is useful for ad-hoc connections to Redis databases that aren't
+    /// configured as profiles, such as standalone Redis instances.
+    pub async fn new_from_url(url: &str) -> anyhow::Result<Self> {
+        debug!(url = %url.split('@').next_back().unwrap_or("[redacted]"), "Connecting to Redis via URL");
+
+        let client = redis::Client::open(url)?;
+        let conn = ConnectionManager::new(client).await?;
+
+        Ok(Self { conn })
+    }
+
     /// Execute an arbitrary Redis command.
     ///
     /// This is the generic execute function that can run any Redis command.

crates/redisctl-mcp/src/lib.rs

@@ -11,7 +11,8 @@
 //!
 //! #[tokio::main]
 //! async fn main() -> anyhow::Result<()> {
-//!     let server = RedisCtlMcp::new(None, true)?; // profile=None, read_only=true
+//!     // profile=None, read_only=true, database_url=None
+//!     let server = RedisCtlMcp::new(None, true, None)?;
 //!     let service = server.serve(stdio()).await?;
 //!     service.waiting().await?;
 //!     Ok(())
@@ -28,17 +29,22 @@ pub use error::McpError;
 pub use server::RedisCtlMcp;
 
 /// Start the MCP server with stdio transport
-pub async fn serve_stdio(profile: Option<&str>, read_only: bool) -> anyhow::Result<()> {
+pub async fn serve_stdio(
+    profile: Option<&str>,
+    read_only: bool,
+    database_url: Option<&str>,
+) -> anyhow::Result<()> {
     use rmcp::{ServiceExt, transport::stdio};
     use tracing::info;
 
     info!(
         profile = profile,
         read_only = read_only,
+        database_url = database_url.map(|_| "[redacted]"),
         "Starting MCP server"
     );
 
-    let server = RedisCtlMcp::new(profile, read_only)?;
+    let server = RedisCtlMcp::new(profile, read_only, database_url)?;
     let service = server.serve(stdio()).await?;
     service.waiting().await?;
 

crates/redisctl-mcp/src/server.rs

@@ -22,6 +22,8 @@ pub struct ServerConfig {
     pub profile: Option<String>,
     /// Whether the server is in read-only mode
     pub read_only: bool,
+    /// Optional database URL for direct connections (overrides profile)
+    pub database_url: Option<String>,
 }
 
 /// MCP server for Redis Cloud and Enterprise management
@@ -1873,15 +1875,21 @@ pub struct PubsubNumsubParam {
 
 impl RedisCtlMcp {
     /// Create a new MCP server instance
-    pub fn new(profile: Option<&str>, read_only: bool) -> anyhow::Result<Self> {
+    pub fn new(
+        profile: Option<&str>,
+        read_only: bool,
+        database_url: Option<&str>,
+    ) -> anyhow::Result<Self> {
         let config = Arc::new(ServerConfig {
             profile: profile.map(String::from),
             read_only,
+            database_url: database_url.map(String::from),
         });
 
         info!(
             profile = ?config.profile,
             read_only = config.read_only,
+            database_url = config.database_url.as_ref().map(|_| "[configured]"),
             "Initializing RedisCtlMcp server"
         );
 
@@ -1924,13 +1932,24 @@ impl RedisCtlMcp {
     }
 
     /// Initialize Database tools lazily
+    ///
+    /// If `database_url` is configured, connects directly using that URL.
+    /// Otherwise, uses the profile-based connection (falls back to default database profile).
     async fn get_database_tools(&self) -> Result<DatabaseTools, RmcpError> {
         let mut guard = self.database_tools.write().await;
         if guard.is_none() {
             debug!("Initializing Database tools");
-            let tools = DatabaseTools::new(self.config.profile.as_deref())
-                .await
-                .map_err(|e| RmcpError::internal_error(e.to_string(), None))?;
+            let tools = if let Some(ref url) = self.config.database_url {
+                debug!("Using direct database URL connection");
+                DatabaseTools::new_from_url(url)
+                    .await
+                    .map_err(|e| RmcpError::internal_error(e.to_string(), None))?
+            } else {
+                debug!("Using profile-based database connection");
+                DatabaseTools::new(self.config.profile.as_deref())
+                    .await
+                    .map_err(|e| RmcpError::internal_error(e.to_string(), None))?
+            };
             *guard = Some(tools);
         }
         Ok(guard.clone().unwrap())
@@ -7450,19 +7469,34 @@ mod tests {
 
     #[test]
     fn test_server_creation() {
-        let server = RedisCtlMcp::new(None, true);
+        let server = RedisCtlMcp::new(None, true, None);
         assert!(server.is_ok());
         let server = server.unwrap();
         assert!(server.config().read_only);
         assert!(server.config().profile.is_none());
+        assert!(server.config().database_url.is_none());
     }
 
     #[test]
     fn test_server_with_profile() {
-        let server = RedisCtlMcp::new(Some("test-profile"), false);
+        let server = RedisCtlMcp::new(Some("test-profile"), false, None);
         assert!(server.is_ok());
         let server = server.unwrap();
         assert!(!server.config().read_only);
         assert_eq!(server.config().profile, Some("test-profile".to_string()));
+        assert!(server.config().database_url.is_none());
+    }
+
+    #[test]
+    fn test_server_with_database_url() {
+        let server = RedisCtlMcp::new(None, true, Some("redis://localhost:6379"));
+        assert!(server.is_ok());
+        let server = server.unwrap();
+        assert!(server.config().read_only);
+        assert!(server.config().profile.is_none());
+        assert_eq!(
+            server.config().database_url,
+            Some("redis://localhost:6379".to_string())
+        );
     }
 }

crates/redisctl/src/cli/mod.rs

@@ -216,11 +216,23 @@ pub enum McpCommands {
 
     # Enable write operations (destructive operations allowed)
     redisctl mcp serve --allow-writes
+
+    # Connect to a specific Redis database
+    redisctl mcp serve --database-url redis://localhost:6379
+
+    # Full access with database connection
+    redisctl mcp serve --allow-writes --database-url redis://:password@localhost:6379
 ")]
     Serve {
         /// Allow write operations (create, update, delete). Default is read-only.
         #[arg(long)]
         allow_writes: bool,
+
+        /// Redis database URL for direct database operations.
+        /// Format: redis[s]://[[username:]password@]host[:port][/db]
+        /// If not specified, uses the default database profile from config.
+        #[arg(long, env = "REDIS_URL")]
+        database_url: Option<String>,
     },
 
     /// List available MCP tools

crates/redisctl/src/main.rs

@@ -225,7 +225,14 @@ fn format_command(command: &Commands) -> String {
         Commands::Mcp(cmd) => {
             use cli::McpCommands::*;
             match cmd {
-                Serve { allow_writes } => format!("mcp serve (allow_writes={})", allow_writes),
+                Serve {
+                    allow_writes,
+                    database_url,
+                } => format!(
+                    "mcp serve (allow_writes={}, database_url={:?})",
+                    allow_writes,
+                    database_url.as_ref().map(|_| "[redacted]")
+                ),
                 Tools => "mcp tools".to_string(),
             }
         }
@@ -237,10 +244,17 @@ async fn execute_mcp_command(cli: &Cli, mcp_cmd: &cli::McpCommands) -> Result<()
     use cli::McpCommands::*;
 
     match mcp_cmd {
-        Serve { allow_writes } => {
+        Serve {
+            allow_writes,
+            database_url,
+        } => {
             let read_only = !allow_writes;
-            debug!("Starting MCP server (read_only={})", read_only);
-            redisctl_mcp::serve_stdio(cli.profile.as_deref(), read_only)
+            debug!(
+                "Starting MCP server (read_only={}, database_url={:?})",
+                read_only,
+                database_url.as_ref().map(|_| "[redacted]")
+            );
+            redisctl_mcp::serve_stdio(cli.profile.as_deref(), read_only, database_url.as_deref())
                 .await
                 .map_err(|e| RedisCtlError::Configuration(e.to_string()))
         }

mkdocs-site/docs/mcp/getting-started.md

@@ -83,7 +83,11 @@ redisctl mcp tools
 
 ### Database Connection Options
 
-The `--database-url` flag enables 125+ database tools for direct Redis operations including all data types, Redis Stack modules (Search, JSON, TimeSeries, Bloom), Streams, and Pub/Sub.
+The MCP server provides 125+ database tools for direct Redis operations including all data types, Redis Stack modules (Search, JSON, TimeSeries, Bloom), Streams, and Pub/Sub. You can connect in two ways:
+
+#### Option 1: Direct URL (Recommended for Ad-Hoc Connections)
+
+Use `--database-url` for quick connections to any Redis database:
 
 ```bash
 # Local Redis
@@ -92,13 +96,51 @@ The `--database-url` flag enables 125+ database tools for direct Redis operation
 # With password
 --database-url redis://:mypassword@localhost:6379
 
+# With username and password
+--database-url redis://myuser:mypassword@localhost:6379
+
 # Redis Cloud/Enterprise database
 --database-url redis://default:password@redis-12345.cloud.redislabs.com:12345
 
-# TLS connection
+# TLS connection (use rediss:// scheme)
 --database-url rediss://default:password@redis-12345.cloud.redislabs.com:12345
+
+# Using environment variable
+REDIS_URL=redis://localhost:6379 redisctl mcp serve
+```
+
+#### Option 2: Database Profile (Recommended for Regular Use)
+
+Configure a database profile in your redisctl config file (`~/.config/redisctl/config.toml` or `~/Library/Application Support/redisctl/config.toml` on macOS):
+
+```toml
+# Default database profile to use when none specified
+default_database_profile = "local-redis"
+
+[profiles.local-redis]
+deployment_type = "database"
+
+[profiles.local-redis.credentials.database]
+host = "localhost"
+port = 6379
+password = "mypassword"  # optional
+tls = false
+username = "default"     # optional, defaults to "default"
+db = 0                   # optional, defaults to 0
+```
+
+Then start the MCP server with that profile:
+
+```bash
+# Uses the default database profile from config
+redisctl mcp serve
+
+# Or specify a profile explicitly
+redisctl -p local-redis mcp serve
 ```
 
+**Note**: If both `--database-url` and a database profile are available, the `--database-url` takes precedence.
+
 ## IDE Configuration
 
 Choose your AI assistant below: