Skip to content

Commit cd94774

Browse files
facundofariasclaude
facundofarias
and
claude
committed
feat: Add read-only mode for security (enabled by default)
Implements read-only mode to protect against accidental or malicious deployment creation when using AI assistants. Server runs in read-only mode by default with explicit opt-out required. Features: - Read-only mode enabled by default (secure by default) - Configuration via DEPLOYHQ_READ_ONLY env var or --read-only CLI flag - CLI flag takes precedence over environment variable - Blocks create_deployment tool with clear, actionable error message - All read operations (list/get) work normally in read-only mode - Comprehensive logging of read-only status at startup Configuration: - Default: read-only enabled (true) - Disable via: DEPLOYHQ_READ_ONLY=false or --read-only=false - Accepts: "true", "false", "1", "0", "yes", "no" (case-insensitive) - Precedence: CLI flag > Environment variable > Default Documentation: - Updated README.md with security section and examples - Updated USER_GUIDE.md with detailed instructions - Added troubleshooting for read-only mode errors Tests: - 48 new tests covering configuration parsing and enforcement - 100% test pass rate (160 tests total) - Tests for all input formats, precedence rules, and edge cases - Integration tests for read-only enforcement and read operations Inspired by Octopus Deploy's MCP server security model. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
1 parent 9e39900 commit cd94774

File tree

11 files changed

+1209
-10
lines changed

11 files changed

+1209
-10
lines changed

‎README.md‎

Lines changed: 80 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -244,6 +244,16 @@ Example:
244244
- Project permalinks are case-sensitive
245245
- Check that you have access to the project in DeployHQ
246246

247+
### Deployment Creation Blocked
248+
249+
**Problem**: "Server is running in read-only mode" error when trying to create deployments
250+
251+
**Solution**:
252+
- The server runs in read-only mode by default for security
253+
- To enable deployments, set `DEPLOYHQ_READ_ONLY=false` in your environment variables
254+
- Or use the `--read-only=false` CLI flag
255+
- See the [Security](#-security) section for detailed instructions
256+
247257
### Deployment Fails
248258

249259
**Problem**: Deployment created but fails immediately
@@ -395,10 +405,79 @@ npm run test:ui # Interactive UI for debugging
395405

396406
## 🔒 Security
397407

408+
### Read-Only Mode (Default)
409+
410+
⚠️ **The DeployHQ MCP Server runs in read-only mode by default** to protect against accidental or malicious deployment creation when using AI assistants.
411+
412+
**What this means:**
413+
- ✅ All read operations work normally (list projects, get deployments, view logs)
414+
- ❌ Deployment creation is blocked and returns a clear error message
415+
- 🛡️ Your production environments are protected by default
416+
417+
**When to disable read-only mode:**
418+
- You explicitly want to enable AI-assisted deployments
419+
- You're using the MCP server in a development/staging environment
420+
- You have additional security controls in place
421+
422+
**How to disable read-only mode:**
423+
424+
Via environment variable:
425+
```json
426+
{
427+
"mcpServers": {
428+
"deployhq": {
429+
"command": "npx",
430+
"args": ["-y", "deployhq-mcp-server"],
431+
"env": {
432+
"DEPLOYHQ_EMAIL": "[email protected]",
433+
"DEPLOYHQ_API_KEY": "your-api-key",
434+
"DEPLOYHQ_ACCOUNT": "your-account",
435+
"DEPLOYHQ_READ_ONLY": "false"
436+
}
437+
}
438+
}
439+
}
440+
```
441+
442+
Via CLI flag:
443+
```json
444+
{
445+
"mcpServers": {
446+
"deployhq": {
447+
"command": "npx",
448+
"args": [
449+
"-y",
450+
"deployhq-mcp-server",
451+
"--read-only=false"
452+
],
453+
"env": {
454+
"DEPLOYHQ_EMAIL": "[email protected]",
455+
"DEPLOYHQ_API_KEY": "your-api-key",
456+
"DEPLOYHQ_ACCOUNT": "your-account"
457+
}
458+
}
459+
}
460+
}
461+
```
462+
463+
**Configuration precedence:**
464+
1. CLI flag `--read-only` (highest priority)
465+
2. Environment variable `DEPLOYHQ_READ_ONLY`
466+
3. Default value: `true` (read-only enabled)
467+
468+
### Additional Security Notes
469+
470+
- **Deployment Logs May Contain Secrets**: Deployment logs can include environment variables, API keys, and other sensitive information. Exercise caution when using tools that retrieve logs, especially with third-party AI services.
471+
472+
- **Use Least-Privilege API Keys**: Create dedicated API keys with minimum required permissions for MCP access. Consider separate keys for read-only vs. read-write operations.
473+
474+
- **Audit MCP Activity**: Monitor MCP usage, especially in production environments. Review logs regularly for unexpected behavior.
475+
398476
- **Environment Variables**: Credentials are never stored, only passed via environment variables
477+
399478
- **HTTPS**: When using npx, credentials stay local to your machine
479+
400480
- **No Telemetry**: No data is sent anywhere except directly to DeployHQ API
401-
- **Minimal Permissions**: Use a dedicated DeployHQ user with minimum required permissions
402481

403482
---
404483

‎docs/USER_GUIDE.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -583,6 +583,79 @@ Choose the scope that best fits your needs. For most users, `--scope user` or us
583583

584584
## 🔒 Security Best Practices
585585

586+
### Read-Only Mode (Default)
587+
588+
⚠️ **The DeployHQ MCP Server runs in read-only mode by default** to protect against accidental or malicious deployment creation when using AI assistants.
589+
590+
**What this means:**
591+
- ✅ All read operations work normally (list projects, get deployments, view logs)
592+
- ❌ Deployment creation is blocked and returns a clear error message
593+
- 🛡️ Your production environments are protected by default
594+
595+
**Disabling Read-Only Mode:**
596+
597+
If you need to create deployments through the MCP server, you can disable read-only mode in two ways:
598+
599+
**Method 1: Environment Variable**
600+
```json
601+
{
602+
"mcpServers": {
603+
"deployhq": {
604+
"command": "npx",
605+
"args": ["-y", "deployhq-mcp-server"],
606+
"env": {
607+
"DEPLOYHQ_EMAIL": "[email protected]",
608+
"DEPLOYHQ_API_KEY": "your-api-key",
609+
"DEPLOYHQ_ACCOUNT": "your-account",
610+
"DEPLOYHQ_READ_ONLY": "false"
611+
}
612+
}
613+
}
614+
}
615+
```
616+
617+
**Method 2: CLI Flag**
618+
```json
619+
{
620+
"mcpServers": {
621+
"deployhq": {
622+
"command": "npx",
623+
"args": [
624+
"-y",
625+
"deployhq-mcp-server",
626+
"--read-only=false"
627+
],
628+
"env": {
629+
"DEPLOYHQ_EMAIL": "[email protected]",
630+
"DEPLOYHQ_API_KEY": "your-api-key",
631+
"DEPLOYHQ_ACCOUNT": "your-account"
632+
}
633+
}
634+
}
635+
}
636+
```
637+
638+
**Configuration Precedence:**
639+
1. CLI flag `--read-only` (highest priority)
640+
2. Environment variable `DEPLOYHQ_READ_ONLY`
641+
3. Default value: `true` (read-only enabled)
642+
643+
**Accepted Values:**
644+
- Enable read-only: `"true"`, `"1"`, `"yes"` (case-insensitive)
645+
- Disable read-only: `"false"`, `"0"`, `"no"` (case-insensitive)
646+
647+
**When to Disable Read-Only Mode:**
648+
- You explicitly want to enable AI-assisted deployments
649+
- You're using the MCP server in a development/staging environment
650+
- You have additional security controls in place
651+
652+
**Security Warning:**
653+
- Deployment logs may contain environment variables, API keys, and secrets
654+
- Exercise extreme caution when using tools that retrieve logs
655+
- Consider using separate API keys for read-only vs. read-write operations
656+
657+
### Additional Security Best Practices
658+
586659
1. **Protect Your Credentials**:
587660
- Never share your API key
588661
- Credentials stay local (environment variables, never transmitted externally)

0 commit comments

Comments
 (0)