Skip to content

Commit 15024c3

Browse files
facundofariasfacundofarias
authored
Merge pull request #2 from deployhq/feature/read-only-mode
feat: Add Optional Read-Only Mode for Deployment Protection
2 parents 9e39900 + 6a58adf commit 15024c3

File tree

11 files changed

+1104
-10
lines changed

11 files changed

+1104
-10
lines changed

‎README.md‎

Lines changed: 85 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+
- Read-only mode is disabled by default, but you may have enabled it
253+
- To disable read-only mode, 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 on read-only mode
256+
247257
### Deployment Fails
248258

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

396406
## 🔒 Security
397407

408+
### Read-Only Mode (Optional)
409+
410+
**By default, the MCP server allows all operations, including creating deployments.** This is the recommended configuration for most users.
411+
412+
For users who want additional protection against accidental deployments, the server includes an **optional read-only mode** that can be enabled to block deployment creation.
413+
414+
**Default Behavior (No Configuration Needed):**
415+
- ✅ Deployments are **allowed by default**
416+
- ✅ All operations work: list, get, and create deployments
417+
- ✅ Full functionality out of the box
418+
419+
**When you might want to enable read-only mode:**
420+
- You want extra protection against accidental deployments via AI
421+
- You're connecting to production environments and want an additional safety layer
422+
- You only need read access to monitor deployments
423+
- You're still testing the integration and want to be cautious
424+
425+
**Important:** Read-only mode is **completely optional**. The server works fully without it.
426+
427+
**How to enable read-only mode:**
428+
429+
Via environment variable:
430+
```json
431+
{
432+
"mcpServers": {
433+
"deployhq": {
434+
"command": "npx",
435+
"args": ["-y", "deployhq-mcp-server"],
436+
"env": {
437+
"DEPLOYHQ_EMAIL": "[email protected]",
438+
"DEPLOYHQ_API_KEY": "your-api-key",
439+
"DEPLOYHQ_ACCOUNT": "your-account",
440+
"DEPLOYHQ_READ_ONLY": "true"
441+
}
442+
}
443+
}
444+
}
445+
```
446+
447+
Via CLI flag:
448+
```json
449+
{
450+
"mcpServers": {
451+
"deployhq": {
452+
"command": "npx",
453+
"args": [
454+
"-y",
455+
"deployhq-mcp-server",
456+
"--read-only"
457+
],
458+
"env": {
459+
"DEPLOYHQ_EMAIL": "[email protected]",
460+
"DEPLOYHQ_API_KEY": "your-api-key",
461+
"DEPLOYHQ_ACCOUNT": "your-account"
462+
}
463+
}
464+
}
465+
}
466+
```
467+
468+
**Configuration precedence:**
469+
1. CLI flag `--read-only` (highest priority)
470+
2. Environment variable `DEPLOYHQ_READ_ONLY`
471+
3. Default value: `false` (deployments allowed)
472+
473+
### Additional Security Notes
474+
475+
- **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.
476+
477+
- **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.
478+
479+
- **Audit MCP Activity**: Monitor MCP usage, especially in production environments. Review logs regularly for unexpected behavior.
480+
398481
- **Environment Variables**: Credentials are never stored, only passed via environment variables
482+
399483
- **HTTPS**: When using npx, credentials stay local to your machine
484+
400485
- **No Telemetry**: No data is sent anywhere except directly to DeployHQ API
401-
- **Minimal Permissions**: Use a dedicated DeployHQ user with minimum required permissions
402486

403487
---
404488

‎docs/USER_GUIDE.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -583,6 +583,90 @@ 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 (Optional)
587+
588+
**By default, the MCP server allows all operations, including creating deployments.** This is the recommended configuration for most users who want full functionality.
589+
590+
For users who want additional protection against accidental deployments, the server includes an **optional read-only mode** that can be enabled to block deployment creation while still allowing read operations.
591+
592+
**Default Behavior (No Configuration Needed):**
593+
- ✅ Deployments are **allowed by default**
594+
- ✅ All operations work: list projects, get details, and create deployments
595+
- ✅ Full functionality out of the box
596+
597+
**When you might want to enable read-only mode:**
598+
- You want extra protection against accidental deployments via AI
599+
- You're connecting to production environments and want an additional safety layer
600+
- You only need read access to monitor deployments
601+
- You're still testing the integration and want to be cautious
602+
603+
**Important:** Read-only mode is **completely optional**. The server works fully without it.
604+
605+
**Enabling Read-Only Mode:**
606+
607+
If you want to prevent deployments through the MCP server, you can enable read-only mode in two ways:
608+
609+
**Method 1: Environment Variable**
610+
```json
611+
{
612+
"mcpServers": {
613+
"deployhq": {
614+
"command": "npx",
615+
"args": ["-y", "deployhq-mcp-server"],
616+
"env": {
617+
"DEPLOYHQ_EMAIL": "[email protected]",
618+
"DEPLOYHQ_API_KEY": "your-api-key",
619+
"DEPLOYHQ_ACCOUNT": "your-account",
620+
"DEPLOYHQ_READ_ONLY": "true"
621+
}
622+
}
623+
}
624+
}
625+
```
626+
627+
**Method 2: CLI Flag**
628+
```json
629+
{
630+
"mcpServers": {
631+
"deployhq": {
632+
"command": "npx",
633+
"args": [
634+
"-y",
635+
"deployhq-mcp-server",
636+
"--read-only"
637+
],
638+
"env": {
639+
"DEPLOYHQ_EMAIL": "[email protected]",
640+
"DEPLOYHQ_API_KEY": "your-api-key",
641+
"DEPLOYHQ_ACCOUNT": "your-account"
642+
}
643+
}
644+
}
645+
}
646+
```
647+
648+
**Configuration Precedence:**
649+
1. CLI flag `--read-only` (highest priority)
650+
2. Environment variable `DEPLOYHQ_READ_ONLY`
651+
3. Default value: `false` (deployments allowed)
652+
653+
**Accepted Values:**
654+
- Enable read-only: `"true"`, `"1"`, `"yes"` (case-insensitive)
655+
- Disable read-only: `"false"`, `"0"`, `"no"` (case-insensitive)
656+
657+
**When to Enable Read-Only Mode:**
658+
- You want to prevent accidental deployments via AI
659+
- You're connecting to production environments
660+
- You want an extra layer of protection
661+
- You only need read access to monitor deployments
662+
663+
**Security Warning:**
664+
- Deployment logs may contain environment variables, API keys, and secrets
665+
- Exercise extreme caution when using tools that retrieve logs
666+
- Consider using separate API keys for read-only vs. read-write operations
667+
668+
### Additional Security Best Practices
669+
586670
1. **Protect Your Credentials**:
587671
- Never share your API key
588672
- Credentials stay local (environment variables, never transmitted externally)

0 commit comments

Comments
 (0)