From a67429c75aab9259ade0714df85629878d4c947e Mon Sep 17 00:00:00 2001 From: Lasim Date: Fri, 24 Oct 2025 21:18:37 +0200 Subject: [PATCH 1/3] feat: Update MCP transport documentation to reflect SDK integration and endpoint changes --- development/satellite/architecture.mdx | 118 +++++++++----------- development/satellite/mcp-transport.mdx | 142 +++++++----------------- 2 files changed, 98 insertions(+), 162 deletions(-) diff --git a/development/satellite/architecture.mdx b/development/satellite/architecture.mdx index 87352f7..3363f5a 100644 --- a/development/satellite/architecture.mdx +++ b/development/satellite/architecture.mdx @@ -24,29 +24,29 @@ Satellites operate as edge workers similar to GitHub Actions runners, providing: ## Current Implementation Architecture -### Phase 1: MCP Transport Layer +### MCP SDK Transport Layer -The current satellite implementation provides complete MCP client interface support: +The satellite uses the official `@modelcontextprotocol/sdk` for all MCP client communication: ``` ┌─────────────────────────────────────────────────────────────────────────────────┐ -│ MCP Transport Implementation │ +│ Official MCP SDK Implementation │ │ │ -│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ -│ │ SSE Transport │ │ SSE Messaging │ │ Streamable HTTP │ │ -│ │ │ │ │ │ │ │ -│ │ • GET /sse │ │ • POST /message │ │ • GET/POST /mcp │ │ -│ │ • Session Mgmt │ │ • JSON-RPC 2.0 │ │ • Optional SSE │ │ -│ │ • 30min timeout │ │ • Session-based │ │ • CORS Support │ │ -│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ MCP SDK Server │ │ +│ │ │ │ +│ │ • StreamableHTTPServerTransport • Standard JSON-RPC handling │ │ +│ │ • Automatic session management • Built-in error responses │ │ +│ │ • Protocol 2025-03-26 compliance • SSE streaming support │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ -│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ -│ │ Session Manager │ │ SSE Handler │ │ Streamable HTTP │ │ -│ │ │ │ │ │ Handler │ │ -│ │ • 32-byte IDs │ │ • Connection │ │ • Dual Response │ │ -│ │ • Activity │ │ Management │ │ • Session Aware │ │ -│ │ • Auto Cleanup │ │ • Message Send │ │ • Error Handle │ │ -│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ MCP Client Integration │ │ +│ │ │ │ +│ │ • StreamableHTTPClientTransport • External server discovery │ │ +│ │ • Automatic connection cleanup • Tool discovery caching │ │ +│ │ • Standard MCP method support • Process communication │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ Foundation Infrastructure │ │ @@ -59,55 +59,47 @@ The current satellite implementation provides complete MCP client interface supp └─────────────────────────────────────────────────────────────────────────────────┘ ``` -### Current MCP Transport Endpoints +### MCP Transport Endpoints -**Implemented Endpoints:** -- `GET /sse` - Establish SSE connection with session management -- `POST /message?session={id}` - Send JSON-RPC messages via SSE sessions -- `GET /mcp` - Establish SSE stream for Streamable HTTP transport -- `POST /mcp` - Send JSON-RPC messages via Streamable HTTP -- `OPTIONS /mcp` - CORS preflight handling +**Active Endpoints:** +- `GET /mcp` - Establish SSE stream via MCP SDK +- `POST /mcp` - Send JSON-RPC messages via MCP SDK +- `DELETE /mcp` - Session termination via MCP SDK **Transport Protocol Support:** ``` -MCP Client Satellite +MCP Client Satellite (MCP SDK) │ │ - │──── GET /sse ─────────────▶│ (Establish SSE session) + │──── POST /mcp ────────────▶│ (Initialize connection) │ │ - │◀─── Session URL ──────────│ (Return session endpoint) + │◀─── Session headers ──────│ (Session established) │ │ - │──── POST /message ────────▶│ (Send JSON-RPC via session) + │──── POST /mcp ────────────▶│ (JSON-RPC tools/list) │ │ - │◀─── Response via SSE ─────│ (Stream response back) + │◀─── Tools response ───────│ (Cached tools returned) ``` -### Core Components - -**Session Manager:** -- Cryptographically secure 32-byte base64url session IDs -- 30-minute session timeout with automatic cleanup -- Activity tracking and session state management -- Client info storage and MCP initialization tracking +### Core SDK Components -**SSE Handler:** -- Server-Sent Events connection establishment -- Message sending with error handling -- Heartbeat and endpoint event management -- Connection lifecycle management +**MCP Server Wrapper:** +- Official SDK Server integration with Fastify +- Standard MCP protocol method handlers +- Automatic session and transport management +- Integration with existing tool discovery and process management -**Streamable HTTP Handler:** -- Dual response mode (JSON and SSE streaming) -- Optional session-based communication -- CORS preflight handling -- Error counting and session management +**Client Communication:** +- StreamableHTTPClientTransport for external server communication +- Automatic connection establishment and cleanup +- Standard MCP method execution (listTools, callTool) +- Built-in error handling and retry logic -### JSON-RPC 2.0 Protocol Implementation +### MCP Protocol Implementation **Supported MCP Methods:** -- `initialize` - MCP session initialization +- `initialize` - MCP session initialization (SDK automatic) - `notifications/initialized` - Client initialization complete -- `tools/list` - List available tools from remote MCP servers -- `tools/call` - Execute tools on remote MCP servers +- `tools/list` - List cached tools from discovered servers +- `tools/call` - Execute tools routed to appropriate servers - `resources/list` - List available resources (returns empty array) - `resources/templates/list` - List resource templates (returns empty array) - `prompts/list` - List available prompts (returns empty array) @@ -115,10 +107,10 @@ MCP Client Satellite For detailed information about tool discovery and execution, see [Tool Discovery Implementation](/development/satellite/tool-discovery). **Error Handling:** -- JSON-RPC 2.0 compliant error responses -- HTTP status code mapping -- Structured error logging -- Session validation and error reporting +- Standard JSON-RPC 2.0 compliant error responses via SDK +- Automatic HTTP status code mapping +- Structured error logging with operation tracking +- Built-in session validation and error reporting ## Planned Full Architecture @@ -414,18 +406,18 @@ npm run dev **Test MCP Transport:** ```bash -# Test SSE connection -curl -N -H "Accept: text/event-stream" http://localhost:3001/sse - -# Send JSON-RPC message (replace SESSION_ID) -curl -X POST "http://localhost:3001/message?session=SESSION_ID" \ +# Test MCP connection +curl -X POST "http://localhost:3001/mcp" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{}}' -# Direct HTTP transport -curl -X POST http://localhost:3001/mcp \ +# Test tool discovery +curl -X POST "http://localhost:3001/mcp" \ -H "Content-Type: application/json" \ - -d '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}' + -d '{"jsonrpc":"2.0","id":"2","method":"tools/list","params":{}}' + +# Test SSE streaming +curl -N -H "Accept: text/event-stream" "http://localhost:3001/mcp" ``` **MCP Client Configuration:** @@ -436,7 +428,7 @@ curl -X POST http://localhost:3001/mcp \ "command": "npx", "args": ["@modelcontextprotocol/server-fetch"], "env": { - "MCP_SERVER_URL": "http://localhost:3001/sse" + "MCP_SERVER_URL": "http://localhost:3001/mcp" } } } diff --git a/development/satellite/mcp-transport.mdx b/development/satellite/mcp-transport.mdx index 2472f2d..777f6f6 100644 --- a/development/satellite/mcp-transport.mdx +++ b/development/satellite/mcp-transport.mdx @@ -1,93 +1,41 @@ --- title: MCP Transport Protocols -description: External communication endpoints for MCP client integration +description: Official MCP SDK transport implementation for external client integration --- # MCP Transport Protocols -Satellite implements three MCP transport protocols for external client communication. Each protocol serves different use cases and client requirements. +Satellite uses the official `@modelcontextprotocol/sdk` to provide MCP client communication. This ensures full protocol compliance and seamless compatibility with all MCP clients including VS Code, Claude, and MCP Inspector. ## Transport Overview -| Protocol | Endpoint | Method | Use Case | -|----------|----------|--------|---------| -| SSE Transport | `/sse` | GET | Persistent connections with session management | -| SSE Messaging | `/message` | POST | JSON-RPC message sending via established sessions | -| Streamable HTTP | `/mcp` | GET/POST | Direct HTTP communication with optional streaming | +| Protocol | Endpoint | Method | Use Case | Implementation | +|----------|----------|--------|----------|---------------| +| Streamable HTTP | `/mcp` | POST | Standard JSON-RPC communication | Official MCP SDK | +| SSE Streaming | `/mcp` | GET | Server-sent events for real-time updates | Official MCP SDK | +| Session Management | `/mcp` | DELETE | Session termination | Official MCP SDK | -## SSE Transport +## MCP SDK Implementation -### Connection Establishment +Satellite leverages the official MCP TypeScript SDK for all transport operations: -**Endpoint:** `GET /sse` +```typescript +import { Server } from '@modelcontextprotocol/sdk/server/index.js'; +import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'; -**Headers:** -- `Accept: text/event-stream` (required) -- `Cache-Control: no-cache` -- `Connection: keep-alive` - -**Response:** -- Content-Type: `text/event-stream` -- Session ID and endpoint URL sent as SSE events -- 30-minute session timeout with automatic cleanup - -**Example:** -```bash -curl -N -H "Accept: text/event-stream" http://localhost:3001/sse -``` - -**SSE Events:** -``` -event: endpoint -data: {"url": "http://localhost:3001/message?session=abc123..."} - -event: heartbeat -data: {"timestamp": "2025-01-09T13:30:00.000Z"} +const server = new Server({ + name: 'deploystack-satellite', + version: '1.0.0' +}); ``` ### Session Management -- **Session ID:** 32-byte cryptographically secure base64url identifier -- **Timeout:** 30 minutes of inactivity -- **Activity Tracking:** Updated on each message received -- **Cleanup:** Automatic removal of expired sessions - -## SSE Messaging - -**Endpoint:** `POST /message?session={sessionId}` - -**Headers:** -- `Content-Type: application/json` (required) - -**Request Body:** JSON-RPC 2.0 message -```json -{ - "jsonrpc": "2.0", - "id": "req-1", - "method": "initialize", - "params": { - "clientInfo": { - "name": "my-client", - "version": "1.0.0" - } - } -} -``` - -**Response:** Message processing status -```json -{ - "status": "sent", - "messageId": "req-1" -} -``` - -**Status Codes:** -- `200` - Message sent successfully -- `202` - Message accepted (for notifications) -- `400` - Invalid JSON-RPC or missing session -- `404` - Session not found -- `500` - Internal server error +The SDK provides automatic session management with: +- **Session ID:** Cryptographically secure identifiers +- **Timeout:** Configurable session timeouts +- **Activity Tracking:** Automatic session activity updates +- **Cleanup:** Built-in session cleanup and resource management ## Streamable HTTP Transport @@ -167,7 +115,7 @@ For detailed information about tool discovery and execution, see [Tool Discovery ### MCP Client Configuration -**SSE Transport Example:** +**Standard Configuration:** ```json { "mcpServers": { @@ -175,25 +123,23 @@ For detailed information about tool discovery and execution, see [Tool Discovery "command": "npx", "args": ["@modelcontextprotocol/server-fetch"], "env": { - "MCP_SERVER_URL": "http://localhost:3001/sse" + "MCP_SERVER_URL": "http://localhost:3001/mcp" } } } } ``` -**Direct HTTP Example:** +**VS Code Configuration:** ```json { - "mcpServers": { - "satellite": { - "command": "npx", - "args": ["@modelcontextprotocol/server-fetch"], - "env": { - "MCP_SERVER_URL": "http://localhost:3001/mcp" - } + "servers": { + "deploystack-satellite": { + "url": "http://localhost:3001/mcp", + "type": "http" } - } + }, + "inputs": [] } ``` @@ -207,29 +153,27 @@ For detailed information about tool discovery and execution, see [Tool Discovery npm run dev ``` -2. **Test SSE Connection:** +2. **Test MCP Connection:** ```bash - curl -N -H "Accept: text/event-stream" http://localhost:3001/sse + curl -X POST "http://localhost:3001/mcp" \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{}}' ``` -3. **Send JSON-RPC Message:** +3. **Test Tools Discovery:** ```bash - curl -X POST "http://localhost:3001/message?session=YOUR_SESSION_ID" \ + curl -X POST "http://localhost:3001/mcp" \ -H "Content-Type: application/json" \ - -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{}}' + -d '{"jsonrpc":"2.0","id":"2","method":"tools/list","params":{}}' ``` -### Protocol Selection - -**Use SSE Transport when:** -- Long-lived connections needed -- Session state management required -- Real-time bidirectional communication +### Protocol Features -**Use Streamable HTTP when:** -- Stateless request/response patterns -- Standard HTTP client libraries -- Optional streaming responses +The official MCP SDK provides: +- **Automatic Session Management:** Sessions created and managed transparently +- **Standard Protocol Compliance:** Full MCP specification 2025-03-26 support +- **Flexible Transport Options:** JSON and SSE streaming responses +- **Built-in Error Handling:** Standard JSON-RPC error responses ## Security Considerations From c8fad50fef0efba09302bdf8b28aae3e7b2104da Mon Sep 17 00:00:00 2001 From: Lasim Date: Fri, 24 Oct 2025 21:59:10 +0200 Subject: [PATCH 2/3] feat: Revise documentation for Docker Compose and production satellite setup, enhancing clarity on deployment types and requirements --- self-hosted/docker-compose.mdx | 53 +- self-hosted/production-satellite.mdx | 742 +++++++++++++++++++++++++++ self-hosted/quick-start.mdx | 83 +-- 3 files changed, 765 insertions(+), 113 deletions(-) create mode 100644 self-hosted/production-satellite.mdx diff --git a/self-hosted/docker-compose.mdx b/self-hosted/docker-compose.mdx index 169cc6d..86b338b 100644 --- a/self-hosted/docker-compose.mdx +++ b/self-hosted/docker-compose.mdx @@ -5,12 +5,18 @@ description: Deploy DeployStack using Docker Compose for a quick and reliable se # Docker Compose Setup -Deploy DeployStack using Docker Compose for a production-ready, self-hosted installation. This method is recommended for most users as it provides a reliable, scalable setup with minimal configuration. +Deploy DeployStack using Docker Compose for a quick and reliable self-hosted installation. This method is recommended for most users as it provides a reliable setup with minimal configuration. Docker containers are for production hosting or self-hosting. For development contributions, check the [Local Setup](/local-setup) guide. + +**Deployment Type**: This guide covers **development and single-team deployments**. The satellite runs without process isolation, suitable for local development or when serving only your own team. + +For **production deployments with multiple teams** or external users, see [Production Satellite Setup](/self-hosted/production-satellite) which includes nsjail process isolation for security and team separation. + + ## Overview This guide provides step-by-step instructions to install and configure DeployStack using Docker Compose. The setup includes frontend, backend, and **required satellite service** with persistent data storage and proper networking. @@ -27,37 +33,6 @@ This guide provides step-by-step instructions to install and configure DeploySta - **Docker & Docker Compose**: Make sure both are installed and up-to-date. - **Storage**: At least 2GB of available disk space for images and persistent data. -### Linux Host Requirements - - -**For Linux deployments only**: To enable nsjail process isolation in the satellite service, your Linux host must have unprivileged user namespaces enabled. - - -Check if already enabled: - -```bash -cat /proc/sys/kernel/unprivileged_userns_clone -# Should return: 1 -``` - -If not enabled (returns 0 or file doesn't exist), enable it: - -```bash -echo 'kernel.unprivileged_userns_clone=1' | sudo tee /etc/sysctl.d/00-userns.conf -sudo sysctl -p /etc/sysctl.d/00-userns.conf -``` - -Verify the setting: - -```bash -cat /proc/sys/kernel/unprivileged_userns_clone -# Should now return: 1 -``` - - -**Note**: This setting is only required for production Linux deployments. Development on macOS/Windows doesn't need this configuration. - - ## Beggining the setup for Docker Compose Follow these steps for a setup with docker compsoe @@ -188,20 +163,6 @@ The satellite service is **already included** in the docker-compose.yml file. Yo **Note**: After initial registration, the satellite saves its API key to persistent storage and doesn't need the registration token for subsequent starts. - -**Alternative for systems without host-level sysctl configuration**: If you cannot modify the host system's kernel parameters, you can add the `--sysctl` flag to the satellite service in your `docker-compose.yml`: - -```yaml -services: - satellite: - # ... other configuration ... - sysctls: - - kernel.unprivileged_userns_clone=1 -``` - -Note that this requires Docker to run with additional privileges and is less secure than configuring the host system directly. - - ## Configuration ### External Access diff --git a/self-hosted/production-satellite.mdx b/self-hosted/production-satellite.mdx new file mode 100644 index 0000000..8290d6e --- /dev/null +++ b/self-hosted/production-satellite.mdx @@ -0,0 +1,742 @@ +--- +title: Production Satellite Setup +description: Deploy a production-ready DeployStack Satellite with nsjail process isolation for multi-team environments on Debian 13. +--- + +# Production Satellite Setup + +This guide covers deploying a production-ready DeployStack Satellite with **nsjail process isolation** for secure multi-team environments. For development or single-team deployments, see the [Quick Start](/self-hosted/quick-start) guide. + + +**When to use this guide:** +- **Production deployments** serving multiple teams +- **Enterprise environments** with strict security requirements +- **Shared infrastructure** where teams need complete isolation +- **Multi-tenant** satellite deployments + +For **development or single-team** usage, the [Docker Compose setup](/self-hosted/docker-compose) is simpler and sufficient. + + +## Overview + +Production satellites provide enterprise-grade security through: + +- **nsjail Process Isolation**: Complete process separation per team with Linux namespaces +- **Resource Limits**: CPU, memory, and process limits per MCP server (2GB RAM, 60s CPU, 1000 processes) +- **Filesystem Jailing**: Read-only system directories, isolated writable spaces +- **Non-Root Execution**: Satellite runs as dedicated `deploystack` user +- **Audit Logging**: Complete activity tracking with automatic rotation + +## Prerequisites + +### System Requirements + +- **Operating System**: Debian 13 (Trixie) - required for nsjail compatibility +- **RAM**: Minimum 4GB (8GB+ recommended for multiple teams) +- **Storage**: 20GB+ available disk space +- **Network**: Outbound HTTPS access to DeployStack Backend +- **Access**: Root/sudo access for initial setup + +### Required Knowledge + +- Linux system administration +- systemd service management +- Basic networking and firewall configuration + +## Installation Process + +The installation follows a two-phase approach: + +1. **System Setup**: Install Node.js, nsjail, configure kernel (run once per server) +2. **Satellite Installation**: Build satellite, configure, create systemd service + + + + Install system dependencies and configure the server for satellite operation. + + + + Build the satellite service and configure it for your environment. + + + + Create systemd service and start the satellite. + + + + Confirm the satellite is running correctly and registered with the backend. + + + +## Phase 1: System Setup + +### Install Node.js 24 + +DeployStack Satellite requires Node.js 24 for compatibility with the latest MCP protocol features. + +```bash +# Add NodeSource repository +curl -fsSL https://deb.nodesource.com/setup_24.x | sudo bash - + +# Install Node.js +sudo apt-get install -y nodejs + +# Verify installation +node --version # Should show v24.x.x +npm --version +``` + +### Install nsjail + +nsjail provides the process isolation that enables secure multi-team satellite operation. + + +**Why nsjail?** nsjail uses Linux namespaces and cgroups to create completely isolated environments for each team's MCP servers. This prevents teams from accessing each other's data or interfering with other processes. + + +```bash +# Install build dependencies +sudo apt-get update +sudo apt-get install -y \ + autoconf \ + bison \ + flex \ + gcc \ + g++ \ + git \ + libprotobuf-dev \ + libnl-route-3-dev \ + libtool \ + make \ + pkg-config \ + protobuf-compiler + +# Clone and build nsjail +cd /tmp +git clone --depth 1 https://github.com/google/nsjail.git +cd nsjail +make + +# Install to system +sudo cp nsjail /usr/local/bin/ +sudo chmod +x /usr/local/bin/nsjail + +# Verify installation +nsjail --version + +# Cleanup +cd / +rm -rf /tmp/nsjail +``` + +### Configure Kernel for User Namespaces + +nsjail requires unprivileged user namespaces to be enabled at the kernel level. + +```bash +# Create sysctl configuration +echo 'kernel.unprivileged_userns_clone=1' | sudo tee /etc/sysctl.d/99-deploystack-userns.conf + +# Apply immediately +sudo sysctl -p /etc/sysctl.d/99-deploystack-userns.conf + +# Verify setting +cat /proc/sys/kernel/unprivileged_userns_clone +# Should return: 1 +``` + + +**Important**: This kernel setting is required for nsjail to function. Without it, all MCP server spawns will fail. The setting persists across reboots via the sysctl configuration file. + + +### Create Service User + +Create a dedicated non-root user for running the satellite service. + +```bash +# Create deploystack user with home directory +sudo useradd -r -s /bin/bash -m -d /opt/deploystack deploystack + +# Verify user creation +id deploystack +``` + +### Set Up Logging Infrastructure + +Configure log directories and rotation for the satellite service. + +```bash +# Create log directory +sudo mkdir -p /var/log/deploystack-satellite +sudo chown deploystack:deploystack /var/log/deploystack-satellite +sudo chmod 755 /var/log/deploystack-satellite + +# Create logrotate configuration +sudo tee /etc/logrotate.d/deploystack-satellite > /dev/null << 'EOF' +/var/log/deploystack-satellite/*.log { + daily + rotate 7 + compress + delaycompress + missingok + notifempty + create 0640 deploystack deploystack + sharedscripts + postrotate + systemctl reload deploystack-satellite > /dev/null 2>&1 || true + endscript +} +EOF +``` + + +**Log Rotation**: Logs rotate daily and retain 7 days of history by default. Adjust the `rotate` value in the logrotate configuration if you need longer retention. + + +## Phase 2: Satellite Installation + +### Clone or Copy Satellite Code + +```bash +# Switch to deploystack user +sudo su - deploystack + +# Clone the repository (or copy satellite code to /opt/deploystack) +cd /opt/deploystack +git clone https://github.com/deploystackio/deploystack.git +cd deploystack/services/satellite +``` + +### Install Dependencies and Build + +```bash +# Install npm dependencies +npm install + +# Build TypeScript code +npm run build + +# Verify build output +ls -la dist/index.js # Should exist +``` + +### Create MCP Cache Directory + +```bash +# Create cache directory for MCP server packages +mkdir -p /opt/deploystack/mcp-cache +``` + +### Configure Environment + +Create the `.env` file with your production configuration. + + +**Registration Token**: You must generate this token from your DeployStack admin interface before proceeding. Navigate to Admin → Satellites → Pairing to generate a global satellite token. + + +```bash +# Create .env file +cat > .env << 'EOF' +# DeployStack Satellite Configuration + +# Server Configuration +PORT=3001 +NODE_ENV=production +LOG_LEVEL=info + +# Backend Connection +DEPLOYSTACK_BACKEND_URL=https://cloud.deploystack.io +DEPLOYSTACK_BACKEND_POLLING_INTERVAL=60 + +# Satellite Identity (10-32 chars, lowercase a-z0-9-_ only) +DEPLOYSTACK_SATELLITE_NAME=prod-satellite-001 + +# Registration Token (from admin panel) +DEPLOYSTACK_REGISTRATION_TOKEN=deploystack_satellite_global_eyJhbGc... + +# Status Display +DEPLOYSTACK_STATUS_SHOW_UPTIME=true +DEPLOYSTACK_STATUS_SHOW_VERSION=true +DEPLOYSTACK_STATUS_SHOW_MCP_DEBUG_ROUTE=false + +# Event System +EVENT_BATCH_INTERVAL_MS=3000 +EVENT_MAX_BATCH_SIZE=100 + +# nsjail Resource Limits +NSJAIL_MEMORY_LIMIT_MB=2048 +NSJAIL_CPU_TIME_LIMIT_SECONDS=60 +NSJAIL_MAX_PROCESSES=1000 +NSJAIL_RLIMIT_NOFILE=1024 +NSJAIL_RLIMIT_FSIZE=50 +NSJAIL_TMPFS_SIZE=100M + +# Process Idle Timeout (seconds, 0 to disable) +MCP_PROCESS_IDLE_TIMEOUT_SECONDS=180 +EOF + +# Secure the environment file +chmod 600 .env +``` + + +**Satellite Name Requirements:** +- Length: 10-32 characters +- Characters: lowercase letters (a-z), numbers (0-9), hyphens (-), underscores (_) +- No spaces or uppercase letters +- Must be unique across your DeployStack deployment + + +### Create Systemd Service + +Exit back to root/sudo user to create the systemd service. + +```bash +# Exit deploystack user +exit + +# Create systemd service file +sudo tee /etc/systemd/system/deploystack-satellite.service > /dev/null << 'EOF' +[Unit] +Description=DeployStack Satellite Service +Documentation=https://docs.deploystack.io +After=network-online.target +Wants=network-online.target + +[Service] +Type=simple +User=deploystack +Group=deploystack +WorkingDirectory=/opt/deploystack/deploystack/services/satellite + +# Start command +ExecStart=/usr/bin/node --env-file=.env dist/index.js + +# Logging +StandardOutput=append:/var/log/deploystack-satellite/satellite.log +StandardError=append:/var/log/deploystack-satellite/error.log + +# Restart policy +Restart=always +RestartSec=10 + +# Security hardening +NoNewPrivileges=true +PrivateTmp=true +ProtectSystem=strict +ProtectHome=true +ReadWritePaths=/opt/deploystack/deploystack/services/satellite/persistent_data +ReadWritePaths=/var/log/deploystack-satellite +ReadWritePaths=/opt/deploystack/mcp-cache + +[Install] +WantedBy=multi-user.target +EOF + +# Reload systemd +sudo systemctl daemon-reload +``` + + +**Security Features**: The systemd service runs with several security hardening options: +- **NoNewPrivileges**: Prevents privilege escalation +- **PrivateTmp**: Isolated /tmp directory +- **ProtectSystem**: Read-only system directories +- **ProtectHome**: Restricted home directory access +- **ReadWritePaths**: Only specific directories are writable + + +### Start the Service + +```bash +# Enable service for automatic startup +sudo systemctl enable deploystack-satellite + +# Start the service +sudo systemctl start deploystack-satellite + +# Check status +sudo systemctl status deploystack-satellite +``` + +## Verification + +### Check Service Status + +```bash +# View service status +sudo systemctl status deploystack-satellite + +# View live logs +sudo tail -f /var/log/deploystack-satellite/satellite.log + +# Check for errors +sudo tail -f /var/log/deploystack-satellite/error.log +``` + +### Verify Port Listening + +```bash +# Check if port 3001 is listening +sudo ss -tlnp | grep :3001 + +# Test health endpoint +curl http://localhost:3001/api/status/backend +``` + +### Check Registration + +Look for successful registration in the logs: + +```bash +sudo grep "registered successfully" /var/log/deploystack-satellite/satellite.log +``` + +You should see: +``` +✅ Satellite registered successfully: prod-satellite-001 +🔑 API key received and ready for authenticated communication +``` + +### Verify in Admin Interface + +1. Log in to your DeployStack admin interface +2. Navigate to Admin → Satellites +3. Confirm your satellite appears with status "Active" +4. Check last heartbeat timestamp is recent + +## Service Management + +### Common Commands + +```bash +# Start service +sudo systemctl start deploystack-satellite + +# Stop service +sudo systemctl stop deploystack-satellite + +# Restart service +sudo systemctl restart deploystack-satellite + +# View status +sudo systemctl status deploystack-satellite + +# Enable auto-start on boot +sudo systemctl enable deploystack-satellite + +# Disable auto-start +sudo systemctl disable deploystack-satellite + +# View logs (last 50 lines) +sudo journalctl -u deploystack-satellite -n 50 + +# Follow logs in real-time +sudo journalctl -u deploystack-satellite -f +``` + +### Updating the Satellite + +```bash +# Stop service +sudo systemctl stop deploystack-satellite + +# Switch to deploystack user +sudo su - deploystack +cd /opt/deploystack/deploystack/services/satellite + +# Pull latest code +git pull + +# Rebuild +npm install +npm run build + +# Exit back to root +exit + +# Start service +sudo systemctl start deploystack-satellite + +# Verify +sudo systemctl status deploystack-satellite +``` + +## Security Considerations + +### nsjail Isolation + +Production satellites use nsjail to provide: + +- **PID Namespace Isolation**: Each team's MCP servers run in separate process trees +- **Mount Namespace Isolation**: Isolated filesystem view per team +- **IPC Namespace Isolation**: Separate inter-process communication +- **UTS Namespace Isolation**: Each team gets unique hostname (mcp-{team_id}) + +### Resource Limits + +Each MCP server process is limited to: + +- **Memory**: 2048MB (absolute minimum for Node.js V8) +- **CPU Time**: 60 seconds +- **Processes**: 1000 (required for npm operations) +- **File Descriptors**: 1024 +- **Maximum File Size**: 50MB + + +**Memory Limit Note**: 2048MB is the absolute minimum for Node.js runtime initialization. Do not reduce this value below 2048MB or MCP servers will fail to start. + + +### Network Security + +Configure firewall rules for production: + +```bash +# Allow only backend communication (satellite polls backend) +# No inbound rules needed - satellite uses outbound polling + +# Optional: Allow local status checks +sudo ufw allow from 127.0.0.1 to any port 3001 + +# If you need external access to satellite (not recommended) +sudo ufw allow 3001/tcp +``` + +## Troubleshooting + +### Service Won't Start + +**Check logs for errors:** +```bash +sudo journalctl -u deploystack-satellite -n 100 +sudo tail -50 /var/log/deploystack-satellite/error.log +``` + +**Common issues:** +- Missing registration token in `.env` +- Invalid satellite name format +- Backend URL unreachable +- Port 3001 already in use + +### nsjail Spawning Failures + +**Symptoms:** +- MCP servers fail to spawn +- Errors mentioning "clone" or "namespace" + +**Check kernel setting:** +```bash +cat /proc/sys/kernel/unprivileged_userns_clone +# Must return: 1 +``` + +**Verify nsjail installation:** +```bash +nsjail --version +which nsjail +``` + +### Registration Fails + +**Check registration token:** +```bash +# View current token in .env (be careful - this is sensitive) +sudo -u deploystack grep REGISTRATION_TOKEN /opt/deploystack/deploystack/services/satellite/.env +``` + +**Common registration issues:** +- Token expired (global tokens expire after 1 hour) +- Token already used (tokens are single-use) +- Backend URL incorrect or unreachable +- Network connectivity issues + +**Test backend connectivity:** +```bash +curl -I https://cloud.deploystack.io +``` + +### High Memory Usage + +**Check process memory:** +```bash +# View satellite memory usage +sudo systemctl status deploystack-satellite | grep Memory + +# View all MCP server processes +ps aux | grep node | grep deploystack +``` + +**Adjust idle timeout to terminate unused processes faster:** +```bash +# Edit .env file +sudo -u deploystack nano /opt/deploystack/deploystack/services/satellite/.env + +# Change MCP_PROCESS_IDLE_TIMEOUT_SECONDS to lower value (e.g., 60) +# Restart service +sudo systemctl restart deploystack-satellite +``` + +### Port Already in Use + +**Find what's using port 3001:** +```bash +sudo lsof -i :3001 +sudo ss -tlnp | grep :3001 +``` + +**Change satellite port:** +```bash +# Edit .env file +sudo -u deploystack nano /opt/deploystack/deploystack/services/satellite/.env + +# Change PORT=3001 to another port +# Restart service +sudo systemctl restart deploystack-satellite +``` + +## Monitoring and Maintenance + +### Log Management + +**View current logs:** +```bash +# Satellite logs +sudo tail -f /var/log/deploystack-satellite/satellite.log + +# Error logs +sudo tail -f /var/log/deploystack-satellite/error.log + +# All logs +sudo tail -f /var/log/deploystack-satellite/*.log +``` + +**Check log disk usage:** +```bash +sudo du -sh /var/log/deploystack-satellite +``` + +**Manual log cleanup:** +```bash +# Remove logs older than 7 days +sudo find /var/log/deploystack-satellite -name "*.log" -mtime +7 -delete +``` + +### Health Monitoring + +Set up automated health checks: + +```bash +# Create health check script +sudo tee /usr/local/bin/check-satellite-health > /dev/null << 'EOF' +#!/bin/bash +if systemctl is-active --quiet deploystack-satellite; then + if curl -sf http://localhost:3001/api/status/backend > /dev/null; then + echo "OK" + exit 0 + else + echo "WARN: Service running but not responding" + exit 1 + fi +else + echo "ERROR: Service not running" + exit 2 +fi +EOF + +sudo chmod +x /usr/local/bin/check-satellite-health + +# Test health check +sudo /usr/local/bin/check-satellite-health +``` + +### Performance Monitoring + +Monitor satellite performance metrics: + +```bash +# CPU and memory usage +top -p $(pgrep -f "deploystack-satellite") + +# Detailed process information +sudo systemctl status deploystack-satellite + +# Network connections +sudo ss -tn | grep :3001 +``` + +## Production Best Practices + +### Backup Configuration + +Regularly backup your satellite configuration: + +```bash +# Backup persistent data and configuration +sudo tar czf /opt/backups/satellite-backup-$(date +%Y%m%d).tar.gz \ + /opt/deploystack/deploystack/services/satellite/.env \ + /opt/deploystack/deploystack/services/satellite/persistent_data +``` + +### Update Strategy + +1. Test updates in staging environment first +2. Schedule maintenance windows for updates +3. Keep backup of previous working version +4. Monitor logs closely after updates + +### Security Auditing + +Regularly review: +- Systemd service permissions +- Log file permissions +- Environment file security (`.env` should be 600) +- User and group ownership + +### Capacity Planning + +Monitor and plan for: +- Number of active MCP server processes +- Memory usage per team +- Log disk usage growth +- Network bandwidth for backend communication + +## Next Steps + + + + Configure MCP servers for your teams + + + + Set up teams and access control + + + + Monitor satellite health and usage + + + + Explore the satellite API + + + +--- + +**Need help?** Join our [Discord community](https://discord.gg/42Ce3S7b3b) or check [GitHub Issues](https://github.com/deploystackio/deploystack/issues) for support. diff --git a/self-hosted/quick-start.mdx b/self-hosted/quick-start.mdx index 6d94070..d9ff113 100644 --- a/self-hosted/quick-start.mdx +++ b/self-hosted/quick-start.mdx @@ -11,43 +11,18 @@ Get DeployStack up and running in minutes. This guide covers deploying the core **Important**: Satellites are required for DeployStack to function. The platform alone cannot manage MCP servers - you must deploy at least one satellite. + +**Deployment Type**: This guide covers **development and single-team deployments**. The satellite runs without process isolation, suitable for local development or when serving only your own team. + +For **production deployments with multiple teams** or external users, see [Production Satellite Setup](/self-hosted/production-satellite) which includes nsjail process isolation for security and team separation. + + ## Prerequisites - **Docker**: [Install Docker](https://docs.docker.com/get-docker/) - **Docker Compose**: [Install Docker Compose](https://docs.docker.com/compose/install/) - **System Requirements**: 4GB RAM, 20GB disk space -### Linux Host Requirements - - -**For Linux deployments only**: To enable nsjail process isolation in the satellite service, your Linux host must have unprivileged user namespaces enabled. - - -Check if already enabled: - -```bash -cat /proc/sys/kernel/unprivileged_userns_clone -# Should return: 1 -``` - -If not enabled (returns 0 or file doesn't exist), enable it: - -```bash -echo 'kernel.unprivileged_userns_clone=1' | sudo tee /etc/sysctl.d/00-userns.conf -sudo sysctl -p /etc/sysctl.d/00-userns.conf -``` - -Verify the setting: - -```bash -cat /proc/sys/kernel/unprivileged_userns_clone -# Should now return: 1 -``` - - -**Note**: This setting is only required for production Linux deployments. Development on macOS/Windows doesn't need this configuration. - - ## Method 1: Docker Compose (Recommended) The fastest way to get DeployStack running with proper networking and persistence. @@ -229,42 +204,16 @@ After completing the basic backend and frontend setup, deploy at least one satel - - - If you configured the host system with unprivileged user namespaces (recommended): - - ```bash - docker run -d \ - --name deploystack-satellite \ - -p 3001:3001 \ - -e DEPLOYSTACK_BACKEND_URL="http://localhost:3000" \ - -e DEPLOYSTACK_SATELLITE_NAME="my-satellite-001" \ - -e DEPLOYSTACK_REGISTRATION_TOKEN="your-token-here" \ - -v deploystack_satellite_persistent:/app/persistent_data \ - deploystack/satellite:latest - ``` - - - - If you cannot modify the host system, pass the sysctl setting at runtime: - - ```bash - docker run -d \ - --name deploystack-satellite \ - --sysctl kernel.unprivileged_userns_clone=1 \ - -p 3001:3001 \ - -e DEPLOYSTACK_BACKEND_URL="http://localhost:3000" \ - -e DEPLOYSTACK_SATELLITE_NAME="my-satellite-001" \ - -e DEPLOYSTACK_REGISTRATION_TOKEN="your-token-here" \ - -v deploystack_satellite_persistent:/app/persistent_data \ - deploystack/satellite:latest - ``` - - - The `--sysctl` flag requires Docker to be run with additional privileges. For production deployments, configuring the host system is preferred. - - - + ```bash + docker run -d \ + --name deploystack-satellite \ + -p 3001:3001 \ + -e DEPLOYSTACK_BACKEND_URL="http://localhost:3000" \ + -e DEPLOYSTACK_SATELLITE_NAME="my-satellite-001" \ + -e DEPLOYSTACK_REGISTRATION_TOKEN="your-token-here" \ + -v deploystack_satellite_persistent:/app/persistent_data \ + deploystack/satellite:latest + ``` **Satellite Name Requirements:** From 27db9d40355dd3da0aabf95258d49d6ab24c83f8 Mon Sep 17 00:00:00 2001 From: Lasim Date: Sat, 25 Oct 2025 21:24:00 +0200 Subject: [PATCH 3/3] feat: Add quick start guide to documentation and update teams structure description --- docs.json | 1 + general/quick-start.mdx | 276 ++++++++++++++++++---------------------- general/teams.mdx | 1 + 3 files changed, 129 insertions(+), 149 deletions(-) diff --git a/docs.json b/docs.json index 3c42616..d9cde88 100644 --- a/docs.json +++ b/docs.json @@ -17,6 +17,7 @@ "group": "Essentials", "pages": [ "index", + "general/quick-start", "general/architecture", "general/teams", "general/roles", diff --git a/general/quick-start.mdx b/general/quick-start.mdx index c150dae..13bb646 100644 --- a/general/quick-start.mdx +++ b/general/quick-start.mdx @@ -1,218 +1,196 @@ --- title: Quick Start -description: Get started with DeployStack in minutes - create your free account, configure MCP servers, and connect instantly with just a URL. +description: Start using MCP tools in under 1 minute with DeployStack - no installation, no configuration files, just connect and go. --- # Quick Start -Get started with DeployStack in minutes. This guide walks you through creating a free account, configuring your first MCP server, and connecting your development environment with zero installation. +Get your first MCP tools running in under 1 minute. We've eliminated the installation friction that holds back MCP adoption - just create an account, click a button, and connect. Your account comes with a pre-installed MCP server ready to test immediately. ## What You'll Accomplish By the end of this guide, you'll have: -- A free DeployStack account with team management -- Your first MCP server configured with secure credentials -- Instant access to MCP tools via satellite URL -- VS Code connected to your team's MCP tools +- A DeployStack account with one pre-installed MCP server +- Your MCP client (VS Code, Cursor, or Claude Desktop) connected to DeployStack Satellite +- Working MCP tools accessible through your client +- Understanding of how to add more MCP servers + +**Time Required:** Under 1 minute (not counting account creation) ## Prerequisites -- **VS Code or Cursor**: For MCP tool integration -- **A few minutes**: This entire setup takes less than 3 minutes -- **No installations required**: Zero local dependencies +You need just two things: + +- **An MCP Client**: VS Code, Cursor IDE, or Claude Desktop +- **A Web Browser**: For OAuth authorization +- **That's it**: No installations, no CLI tools, no configuration file editing -## Step 1: Create Your Free Account +## The 3-Step Setup + +### Step 1: Create Your Account - - Visit [cloud.deploystack.io](https://cloud.deploystack.io) and create your free account: + + Visit [cloud.deploystack.io](https://cloud.deploystack.io) and create your free account. - - Sign up with your email address or GitHub account - - Complete email verification if required - - You'll automatically get your own default team + You can sign up with: + - Email address + - GitHub account - Once logged in, you'll see preinstalled MCP servers in your dashboard. - We have preinstalled popular MCP servers like Sequential Thinking. You can add more whenever you want to. + Once logged in, you'll see your dashboard with: + - One pre-installed MCP server ready to use + - "Get Client Configuration" button in the top-right corner + - Empty team space ready for collaboration + + We pre-install a demo MCP server so you can test the platform immediately without adding anything first. -## Step 2: Get Your OAuth Credentials +### Step 2: Connect Your MCP Client -DeployStack Satellite provides instant MCP access through managed infrastructure - no installation required. +Now connect your MCP client to DeployStack Satellite. This is where the "zero installation" comes in - no CLI tools to install, no npm packages to manage, just click and connect. - + In your DeployStack dashboard: - 1. Navigate to the **Satellite** section - 2. Click **Create MCP Client Credentials** - 3. Enter a name for your client (e.g., "VS Code", "Claude Desktop") - 4. Copy the generated OAuth credentials: - - **Client ID**: `deploystack_mcp_client_abc123def456ghi789` - - **Client Secret**: `deploystack_mcp_secret_xyz789abc123def456ghi789jkl012` + 1. Click the **"Get Client Configuration"** button (top-right corner) + 2. A modal opens showing supported MCP clients + 3. Select your client from the dropdown: + - VS Code + - Cursor IDE + - Claude Desktop + + + + Depending on your client, you'll see one of two options: + + **For Cursor IDE:** + - Click the **"Install in Cursor"** button + - Cursor opens automatically with configuration applied + - Done! Skip to Step 3 - These OAuth credentials provide secure access to your team's MCP servers through standard OAuth Bearer Token authentication. + **For VS Code or Claude Desktop:** + - Copy the JSON configuration shown in the modal + - Open your MCP client settings + - Paste the configuration + - Save the settings file -## Step 3: Connect Your Development Environment + + **What Just Happened?** + + You added the DeployStack Satellite URL to your MCP client. Instead of running MCP servers locally, your client now connects to our managed infrastructure where your MCP servers run securely with your team's credentials. + + +### Step 3: Authorize the Connection -Now connect VS Code or Cursor to use your team's MCP servers via satellite. +The final step happens automatically when you connect - DeployStack uses OAuth2.1 for secure, credential-free authorization. - - Open your VS Code settings and configure MCP to use the DeployStack Satellite. - - **Location**: `.vscode/settings.json` or global VS Code settings - - **Before** (manual MCP server management): - - ```json - { - "mcpServers": { - "github": { - "command": "npx", - "args": ["@github/mcp"], - "env": { - "GITHUB_TOKEN": "your-token-here" - } - } - } - } - ``` - - **After** (DeployStack Satellite): - - ```json - { - "mcpServers": { - "deploystack": { - "url": "https://satellite.deploystack.io/mcp", - "oauth": { - "client_id": "deploystack_mcp_client_abc123def456ghi789", - "client_secret": "deploystack_mcp_secret_xyz789abc123def456ghi789jkl012" - }, - "name": "DeployStack Satellite", - "description": "MCP-as-a-Service with zero installation" - } - } - } - ``` + + In your MCP client: + - Click **"Connect"** or **"Start"** next to the DeployStack Satellite entry + - Your web browser opens automatically - - 1. **Restart VS Code** to load the new MCP configuration - 2. **Open Claude or compatible MCP client** - 3. **Test a tool**: Try using one of your configured MCP servers - 4. **Verify**: Tools should work instantly without any local setup + + In the browser window: + 1. You'll see your available teams + 2. Select the team you want to use + 3. Click **"Authorize"** + 4. Browser window closes automatically + + + + Back in your MCP client: + - Connection status shows "Connected" + - Your pre-installed MCP server is now available + - You can start using MCP tools immediately -## Step 4: Explore Your Setup +## Verify It Works -Now that everything is connected, explore what you can do: +Let's make sure your MCP connection is working by testing your pre-installed server. - - In your VS Code MCP client: - - All configured MCP tools are instantly available - - No local processes or installations required - - Tools automatically include your team's credentials + + In VS Code, Cursor, or Claude Desktop, open the MCP tools panel or command palette. - - View activity in your [DeployStack dashboard](https://cloud.deploystack.io): - - Real-time MCP tool usage - - Team activity and analytics - - Satellite performance metrics + + You should see tools from your pre-installed MCP server listed. + + Try running one of the available tools to confirm everything works. - - Back in the [DeployStack dashboard](https://cloud.deploystack.io): - - Add more MCP servers to your team - - Manage credentials securely - - Monitor satellite usage + + Go back to [cloud.deploystack.io](https://cloud.deploystack.io) and check: + - Your dashboard shows connection activity + - You can see which MCP server is active + - Usage analytics start appearing -## Managing Your Satellite Connection - -With DeployStack Satellite, management is done through the web dashboard: - -- **Configuration**: All changes made in [cloud.deploystack.io](https://cloud.deploystack.io) -- **Instant Updates**: Changes take effect immediately, no local updates needed -- **Team Switching**: Change teams in the dashboard, regenerate token if needed -- **Monitoring**: View real-time usage and performance metrics -- **Zero Maintenance**: No local processes to start, stop, or restart - -## Multiple Teams - -If you're part of multiple teams or create additional teams: - -1. **Switch Teams**: Use the team selector in your [DeployStack dashboard](https://cloud.deploystack.io) -2. **Generate New OAuth Credentials**: Each team requires separate OAuth client credentials for security -3. **Update VS Code**: Replace the oauth client_id and client_secret with the new team's credentials -4. **Instant Access**: New team's MCP tools are immediately available - -When you switch teams: -- New team's MCP servers become available instantly -- Previous team's tools are no longer accessible (security isolation) -- All team-specific credentials are automatically applied + + **🎉 You're Done!** + + You now have a working MCP connection through DeployStack Satellite. Your pre-installed MCP server is running on managed infrastructure, and you can add more servers anytime from the catalog. + ## What's Next? ### Add More MCP Servers -Expand your toolkit by adding more MCP servers: -- **BrightData**: Web scraping and data collection -- **Weather**: Weather information and forecasts -- **Database**: Connect to your databases -- **Custom Servers**: Add your own private MCP servers +Your account comes with one pre-installed server, but DeployStack offers access to hundreds of MCP servers from the official registry: -### Team Collaboration +1. **Browse the Catalog**: Visit the [MCP Server](https://cloud.deploystack.io/) in your dashboard +2. **Choose Servers**: Browse by category or search for specific tools +3. **Add to Team**: Click "Add to Team" on any server +4. **Configure Credentials**: Add required credentials (API keys, tokens, etc.) +5. **Instant Access**: Server appears in your MCP client immediately -If you're working with a team: -- **[Invite Team Members](/onboard-new-team-members)**: Add developers to your team -- **[Manage Roles](/roles)**: Set up proper access control -- **[Team Management](/teams)**: Organize multiple projects +For more details, see the [MCP Server Catalog Guide](/general/mcp-catalog). -## Troubleshooting +### Invite Team Members -### Satellite Connection Issues +DeployStack is built for team collaboration: -1. **Check OAuth credentials**: - - Verify your client_id and client_secret are correct - - Regenerate OAuth credentials in dashboard if needed +1. **Navigate to Team Settings**: Go to your team page +2. **Click "Invite Members"**: Enter email addresses +3. **Set Roles**: Choose appropriate permissions +4. **Send Invitations**: Team members receive email invitations +5. **Instant Sharing**: Once they accept, they get access to all team MCP servers -2. **Verify VS Code configuration**: - - Ensure the satellite URL is `https://satellite.deploystack.io/mcp` - - Check oauth section has your current client_id and client_secret - - Restart VS Code after configuration changes +## Working with Multiple Teams -3. **Test connection**: - ```bash - curl -X POST https://satellite.deploystack.io/mcp \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_OAUTH_TOKEN" \ - -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' - ``` +If you're part of multiple teams or create additional teams: -### MCP Tools Not Working +1. **Switch Teams in Dashboard**: Use the team selector at [cloud.deploystack.io](https://cloud.deploystack.io) +2. **Disconnect in MCP Client**: Disconnect from DeployStack Satellite +3. **Reconnect**: Click "Connect" again +4. **Choose Different Team**: In the OAuth browser window, select the new team +5. **Authorize**: Your MCP client now uses the new team's servers -1. **Check satellite status**: Visit your [dashboard](https://cloud.deploystack.io) for real-time status -2. **Verify credentials**: Ensure OAuth credentials are properly configured for your team -3. **Client permissions**: Confirm your OAuth client has access to the required MCP servers +**Each team has:** +- Separate MCP server configurations +- Independent credentials and API keys +- Isolated usage and analytics +- Team-specific access control -### Need Help? +## Get Help -- **Community**: Join our [Discord](https://discord.gg/42Ce3S7b3b) -- **Documentation**: Browse our [full documentation](/) -- **Support**: Contact support for technical issues +### Community Support ---- +- **Discord**: Join our [Discord community](https://discord.gg/42Ce3S7b3b) for real-time help +- **GitHub Discussions**: Ask questions at [github.com/deploystackio/deploystack](https://github.com/deploystackio/deploystack) -**🎉 Congratulations!** You now have DeployStack Satellite configured and running. Your development environment is connected to enterprise-grade MCP management with zero installation, secure credential handling, and instant team collaboration. +### Documentation -**Next Steps**: Explore the [MCP Catalog](https://cloud.deploystack.io) to add more tools to your team, or invite colleagues to collaborate on your projects. +- **Full Docs**: Browse our complete documentation at [docs.deploystack.io](https://docs.deploystack.io) +- **MCP Catalog**: Learn about available servers at [MCP Server Catalog](/general/mcp-catalog) +- **Team Management**: Read [Team Management Guide](/general/teams) for collaboration features diff --git a/general/teams.mdx b/general/teams.mdx index 7fabf79..53f0bf5 100644 --- a/general/teams.mdx +++ b/general/teams.mdx @@ -1,6 +1,7 @@ --- title: Teams Structure in DeployStack description: Organize your MCP server management with teams - your workspace for managing servers and configurations in DeployStack. +sidebarTitle: Teams --- # Teams