# SSH Session MCP - AI Agent Guide
## Overview
Persistent SSH sessions for remote server management. Sessions survive across tool calls.
## Quick Reference
### Connect
```
ssh_connect(host="server.com", auth_mode="password", username="deploy")
→ { session_id: "abc-123", status: "connected" }
```
### Execute Commands
```
ssh_exec(session_id="abc-123", command="cd /app && git pull")
→ { stdout: "...", exit_code: 0, status: "completed" }
```
### Background Tasks
```
ssh_exec(session_id="abc-123", command="npm run build", background=true)
→ { status: "running", pid: "12345" }
ssh_read_buffer(session_id="abc-123", lines=100)
→ { lines: [...output...], total_buffered: 500 }
```
### File Transfer
```
scp_upload(session_id="abc-123", local_path="./config.json", remote_path="/app/config.json")
scp_download(session_id="abc-123", remote_path="/app/logs/app.log", local_path="./app.log")
```
### Cleanup
```
ssh_disconnect(session_id="abc-123")
```
## Best Practices
1. **Reuse sessions** - Same session_id for all commands to same host
2. **Check existing** - Use `list_sessions()` before connecting
3. **Background for long tasks** - Use `background=true` for builds/deploys
4. **Combine commands** - Use `&&` to chain: `cd /app && git pull && npm install`
5. **Disconnect when done** - Clean up after completing tasks
## Error Handling
| Status | Meaning |
|--------|---------|
| `connected` | Ready for commands |
| `awaiting_credentials` | User will see GUI prompt |
| `error` | Check message for details |
| `timeout` | Use background mode |
## Typical Workflow
```
1. list_sessions() - Check for existing connection
2. ssh_connect(...) - Connect if needed
3. ssh_exec(...) - Run commands
4. scp_upload/download(...) - Transfer files if needed
5. ssh_disconnect(...) - Clean up
```
