# SmartSuite MCP Server - Deployment Guide
## Overview
This guide covers deployment strategies for SmartSuite MCP Server in various environments, from local development to production.
**Target Environments:**
- Local Development (with Claude Desktop/Code)
- Docker Containers
- Cloud Platforms (AWS, GCP, Azure)
- CI/CD Integration
---
## Table of Contents
1. [Prerequisites](#prerequisites)
2. [Local Development](#local-development)
3. [Docker Deployment](#docker-deployment)
4. [Production Deployment](#production-deployment)
5. [Claude Desktop Integration](#claude-desktop-integration)
6. [Environment Configuration](#environment-configuration)
7. [Health Checks & Monitoring](#health-checks--monitoring)
8. [Security Considerations](#security-considerations)
9. [Troubleshooting](#troubleshooting)
---
## Prerequisites
### System Requirements
- **Node.js**: v18.0.0 or higher (v20.x recommended)
- **npm**: v10.x or higher
- **Memory**: Minimum 512MB, recommended 1GB+
- **Disk**: 200MB for application + dependencies
### SmartSuite Requirements
- Valid SmartSuite API token
- Workspace ID
- Appropriate permissions for intended operations
### Optional
- Docker (for containerized deployment)
- Git (for version control)
---
## Local Development
### Quick Start
```bash
# Clone repository
git clone <repository-url>
cd smartsuite-mcp
# Install dependencies
npm install
# Configure environment
cp .env.example .env
# Edit .env with your credentials
# Run quality gates
npm run quality-gates
# Build project
npm run build
# Start server
npm start
```
### Development Mode (Hot Reload)
```bash
# Run with auto-reload on file changes
npm run dev
```
### Testing
```bash
# Run all tests
npm test
# Run with coverage
npm run test:coverage
# Run in watch mode
npm run test:watch
# Run only unit tests
npm run test:unit
```
### Quality Gates
```bash
# Run all quality checks (required before commit)
npm run quality-gates
# Individual checks
npm run lint # ESLint
npm run typecheck # TypeScript
npm run test:ci # Unit tests
```
---
## Docker Deployment
### Using Docker
```bash
# Build image
docker build -t smartsuite-mcp:latest .
# Run container
docker run -d \
--name smartsuite-mcp \
-e SMARTSUITE_API_KEY=your-api-key \
-e SMARTSUITE_WORKSPACE_ID=your-workspace-id \
-v $(pwd)/config:/app/config \
smartsuite-mcp:latest
```
### Using Docker Compose
```bash
# Start services
docker-compose up -d
# View logs
docker-compose logs -f smartsuite-mcp
# Stop services
docker-compose down
```
### Docker Compose Configuration
```yaml
version: '3.8'
services:
smartsuite-mcp:
image: smartsuite-mcp:latest
build: .
environment:
- SMARTSUITE_API_KEY=${SMARTSUITE_API_KEY}
- SMARTSUITE_WORKSPACE_ID=${SMARTSUITE_WORKSPACE_ID}
- NODE_ENV=production
- LOG_LEVEL=info
volumes:
- ./config:/app/config
- ./logs:/app/logs
restart: unless-stopped
healthcheck:
test: ["CMD", "node", "-e", "process.exit(0)"]
interval: 30s
timeout: 10s
retries: 3
```
---
## Production Deployment
### Build for Production
```bash
# Install production dependencies only
npm ci --production
# Run quality gates
npm run quality-gates
# Build TypeScript
npm run build
# Validate build
npm run validate-build
```
### Environment Setup
```bash
# Production .env configuration
NODE_ENV=production
LOG_LEVEL=info
# SmartSuite credentials
SMARTSUITE_API_KEY=<production-api-key>
SMARTSUITE_WORKSPACE_ID=<production-workspace-id>
SMARTSUITE_API_URL=https://app.smartsuite.com/api/v1
# Optional: Force dry-run safety
SMARTSUITE_DRY_RUN=false # Set to true to prevent ALL mutations
```
### Process Management
#### Using PM2
```bash
# Install PM2
npm install -g pm2
# Start server
pm2 start build/src/index.js --name smartsuite-mcp
# Configuration file (ecosystem.config.js)
module.exports = {
apps: [{
name: 'smartsuite-mcp',
script: 'build/src/index.js',
instances: 1,
autorestart: true,
watch: false,
max_memory_restart: '1G',
env: {
NODE_ENV: 'production',
LOG_LEVEL: 'info'
}
}]
};
# Start with config
pm2 start ecosystem.config.js
# Monitor
pm2 monit
# Logs
pm2 logs smartsuite-mcp
# Restart
pm2 restart smartsuite-mcp
# Stop
pm2 stop smartsuite-mcp
```
#### Using systemd
```bash
# Create service file: /etc/systemd/system/smartsuite-mcp.service
[Unit]
Description=SmartSuite MCP Server
After=network.target
[Service]
Type=simple
User=smartsuite
WorkingDirectory=/opt/smartsuite-mcp
Environment="NODE_ENV=production"
EnvironmentFile=/opt/smartsuite-mcp/.env
ExecStart=/usr/bin/node /opt/smartsuite-mcp/build/src/index.js
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target
# Enable and start
sudo systemctl enable smartsuite-mcp
sudo systemctl start smartsuite-mcp
# Check status
sudo systemctl status smartsuite-mcp
# View logs
sudo journalctl -u smartsuite-mcp -f
```
---
## Claude Desktop Integration
### Configuration
Add to Claude Desktop MCP configuration file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**Linux**: `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"smartsuite": {
"command": "node",
"args": ["/absolute/path/to/smartsuite-mcp/build/src/index.js"],
"env": {
"SMARTSUITE_API_KEY": "your-api-token",
"SMARTSUITE_WORKSPACE_ID": "your-workspace-id",
"LOG_LEVEL": "info"
}
}
}
}
```
### Verification
1. Restart Claude Desktop
2. Open a new conversation
3. Check for SmartSuite tools in the tools menu
4. Test with: "List tools available" or "Use smartsuite_discover to list tables"
---
## Environment Configuration
### Required Variables
| Variable | Description | Example |
|----------|-------------|---------|
| `SMARTSUITE_API_KEY` | SmartSuite API token | `abc123...` |
| `SMARTSUITE_WORKSPACE_ID` | Workspace identifier | `s3qnmox1` |
### Optional Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `SMARTSUITE_API_URL` | `https://app.smartsuite.com/api/v1` | API base URL |
| `SMARTSUITE_DRY_RUN` | `false` | Force dry-run for all mutations |
| `NODE_ENV` | `development` | Environment mode |
| `LOG_LEVEL` | `info` | Logging level: `error`, `warn`, `info`, `debug` |
| `DEBUG` | `false` | Enable debug mode |
### Configuration File Locations
```
.env # Local environment
config/field-mappings/*.yaml # Field translations
config/knowledge/ # Safety pattern knowledge base
```
### Security Best Practices
1. **Never commit `.env` files**
2. **Use environment-specific credentials** (dev/staging/prod)
3. **Rotate API keys regularly**
4. **Use read-only keys** when possible
5. **Enable audit logging** in production
---
## Health Checks & Monitoring
### Validation Mode
Test configuration without starting server:
```bash
MCP_VALIDATE_AND_EXIT=true npm start
```
### Health Check Script
```bash
#!/bin/bash
# health-check.sh
# Check if process is running
if ! pgrep -f "build/src/index.js" > /dev/null; then
echo "ERROR: SmartSuite MCP Server not running"
exit 1
fi
# Check API connectivity (requires curl and valid credentials)
RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" \
-H "Authorization: Token $SMARTSUITE_API_KEY" \
-H "ACCOUNT-ID: $SMARTSUITE_WORKSPACE_ID" \
https://app.smartsuite.com/api/v1/applications/)
if [ "$RESPONSE" != "200" ]; then
echo "ERROR: SmartSuite API unreachable (HTTP $RESPONSE)"
exit 1
fi
echo "OK: SmartSuite MCP Server healthy"
exit 0
```
### Monitoring Metrics
Key metrics to track:
- **Process Uptime**: Server restart frequency
- **API Response Time**: SmartSuite API latency
- **Error Rate**: Failed operations / total operations
- **Memory Usage**: Detect memory leaks
- **Token Usage**: MCP context window utilization
### Logging
```bash
# Production logging configuration
LOG_LEVEL=info # Only log info, warn, error
# Development logging
LOG_LEVEL=debug # Verbose output
# Log file locations
logs/application.log # Application logs
logs/error.log # Error logs only
logs/access.log # API access logs
```
---
## Security Considerations
### 1. API Key Management
```bash
# Use secrets management
export SMARTSUITE_API_KEY=$(aws secretsmanager get-secret-value --secret-id smartsuite-api-key --query SecretString --output text)
# Or use encrypted environment files
ansible-vault encrypt .env.production
```
### 2. Network Security
```bash
# Run behind reverse proxy
# nginx configuration example
location /mcp/ {
proxy_pass http://localhost:3000/;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
# Rate limiting
limit_req zone=mcp_limit burst=10 nodelay;
}
```
### 3. Firewall Rules
```bash
# Only allow necessary outbound connections
ufw allow out 443/tcp # HTTPS to SmartSuite API
ufw allow out 53/udp # DNS
```
### 4. Container Security
```dockerfile
# Use non-root user
USER node
# Read-only filesystem
RUN chmod -R 555 /app
# Drop capabilities
--cap-drop=ALL
```
---
## CI/CD Integration
### GitHub Actions
```yaml
name: Deploy to Production
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20.x'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Run quality gates
run: npm run quality-gates
- name: Build
run: npm run build
- name: Deploy
run: |
# Your deployment commands here
scp -r build/ user@server:/opt/smartsuite-mcp/
ssh user@server 'pm2 restart smartsuite-mcp'
```
### GitLab CI
```yaml
stages:
- test
- build
- deploy
test:
stage: test
script:
- npm ci
- npm run quality-gates
build:
stage: build
script:
- npm run build
artifacts:
paths:
- build/
deploy:
stage: deploy
script:
- scp -r build/ $DEPLOY_SERVER:/opt/smartsuite-mcp/
- ssh $DEPLOY_SERVER 'pm2 restart smartsuite-mcp'
only:
- main
```
---
## Troubleshooting
### Common Issues
**Server won't start**
```bash
# Check Node version
node --version # Should be 18.x or higher
# Verify build
npm run build
# Check environment variables
env | grep SMARTSUITE
# Run in debug mode
DEBUG=true npm start
```
**API connection failures**
```bash
# Test API connectivity
curl -H "Authorization: Token $SMARTSUITE_API_KEY" \
-H "ACCOUNT-ID: $SMARTSUITE_WORKSPACE_ID" \
https://app.smartsuite.com/api/v1/applications/
# Check firewall/proxy settings
```
**Memory issues**
```bash
# Increase Node memory limit
NODE_OPTIONS="--max-old-space-size=2048" npm start
# Monitor memory usage
top -p $(pgrep -f "build/src/index.js")
```
For more issues, see [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)
---
## Deployment Checklist
### Pre-Deployment
- [ ] Run quality gates: `npm run quality-gates`
- [ ] Update dependencies: `npm audit fix`
- [ ] Review security advisories
- [ ] Test with validation mode
- [ ] Backup configuration files
- [ ] Update documentation
### Deployment
- [ ] Build production artifacts
- [ ] Set environment variables
- [ ] Deploy to target environment
- [ ] Verify health checks
- [ ] Test core functionality
- [ ] Monitor error logs
### Post-Deployment
- [ ] Verify all tools accessible
- [ ] Test with real requests
- [ ] Monitor performance metrics
- [ ] Set up alerting
- [ ] Document deployment date/version
- [ ] Update changelog
---
## Support
- **Documentation**: [docs/](./README.md)
- **API Reference**: [docs/API.md](./API.md)
- **Architecture**: [docs/001-ARCHITECTURE.md](./001-ARCHITECTURE.md)
- **Security**: [SECURITY.md](../SECURITY.md)
- **Issues**: GitHub Issues
---
**Version**: 1.0.0
**Last Updated**: 2025-11-11
**License**: MIT
