Skip to content

Commit 2ba92ec

Browse files
LasimLasim
authored
Merge pull request #300 from deploystackio/feat/limits
docs: Add limitations documentation and update index to include new page
2 parents a804028 + aa10446 commit 2ba92ec

File tree

3 files changed

+160
-3
lines changed

3 files changed

+160
-3
lines changed

‎docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
"pages": [
1919
"index",
2020
"general/quick-start",
21+
"general/limitations",
2122
"general/architecture",
2223
"general/teams",
2324
"general/roles",

‎general/limitations.mdx‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
---
2+
title: Platform Limitations
3+
description: Understand when DeployStack global satellites work and when you need local MCP or team satellites instead
4+
---
5+
6+
DeployStack runs MCP servers on **remote satellite infrastructure** - not on your local machine. This architecture provides zero-installation convenience but means some MCP servers won't work on global satellites.
7+
8+
This page helps you understand what works, what doesn't, and your alternatives.
9+
10+
## How Satellites Work
11+
12+
When you install an MCP server from the DeployStack catalog, the satellite:
13+
14+
1. Spawns the MCP server process on remote infrastructure
15+
2. Executes tool calls on the satellite, not your machine
16+
3. Returns results back to your AI client
17+
18+
This means the MCP server has access to the **satellite's environment**, not yours.
19+
20+
## What Doesn't Work on Global Satellites
21+
22+
### Local File Access
23+
24+
MCP servers that need to read or write files on your machine won't work:
25+
26+
| MCP Server | Why It Doesn't Work |
27+
|------------|---------------------|
28+
| SQLite MCP | Cannot access your local `.db` files |
29+
| Filesystem MCP | Cannot browse your local directories |
30+
| Obsidian MCP | Cannot access your local vault |
31+
| Desktop Commander | Cannot control your local desktop |
32+
33+
<Warning>
34+
Any MCP server that reads `~/Documents`, `/home/user/`, or similar local paths will only see the satellite's filesystem - not yours.
35+
</Warning>
36+
37+
### Local Network Resources
38+
39+
MCP servers that connect to `localhost` or internal network services:
40+
41+
| Resource | Example |
42+
|----------|---------|
43+
| Local databases | `localhost:5432` (PostgreSQL), `localhost:3306` (MySQL) |
44+
| Local APIs | `http://localhost:8080/api` |
45+
| Internal services | `http://internal.company.com` (behind firewall) |
46+
| Development servers | Your local dev environment |
47+
48+
The satellite cannot reach services running on your machine or inside your corporate network.
49+
50+
### Desktop & GUI Applications
51+
52+
MCP servers requiring graphical interfaces or desktop integration:
53+
54+
| MCP Server | Limitation |
55+
|------------|------------|
56+
| Playwright (headed mode) | No display server on satellites |
57+
| Puppeteer (headed mode) | Same issue - no visible browser |
58+
| Screenshot tools | No desktop to capture |
59+
| Clipboard MCP | No access to your clipboard |
60+
61+
<Info>
62+
**Playwright and Puppeteer can work in headless mode**, but require browser binaries pre-installed on the satellite. This is not available on global satellites by default.
63+
</Info>
64+
65+
### Hardware Access
66+
67+
MCP servers that interact with physical devices:
68+
69+
- USB devices
70+
- Printers
71+
- Cameras and microphones
72+
- Serial ports
73+
- Bluetooth devices
74+
75+
## Your Alternatives
76+
77+
### Option 1: Run Locally
78+
79+
For MCP servers that need local resources, run them on your machine i.e.:
80+
81+
```json
82+
{
83+
"mcpServers": {
84+
"sqlite": {
85+
"command": "npx",
86+
"args": ["-y", "@anthropic/mcp-sqlite", "/path/to/your/database.db"]
87+
}
88+
}
89+
}
90+
```
91+
92+
You can use DeployStack for most MCP servers and run specific ones locally.
93+
94+
### Option 2: Deploy a Team Satellite
95+
96+
For internal network access, deploy a [Team Satellite](/self-hosted/production-satellite) inside your infrastructure:
97+
98+
- Runs within your corporate network
99+
- Can access internal databases and APIs
100+
- You control what's installed (including browser binaries)
101+
- Full process isolation with nsjail
102+
103+
Team satellites connect to your DeployStack control plane but run on your hardware.
104+
105+
### Option 3: Use Cloud-Accessible Resources
106+
107+
Instead of local resources, use cloud alternatives:
108+
109+
| Local Resource | Cloud Alternative |
110+
|----------------|-------------------|
111+
| Local SQLite | Turso, PlanetScale, Supabase |
112+
| Local files | S3, Google Drive, Dropbox |
113+
| Local PostgreSQL | Neon, Supabase, RDS |
114+
| Internal APIs | Expose via tunnel (Cloudflare, ngrok) |
115+
116+
## What Works Well on Global Satellites
117+
118+
Global satellites excel at MCP servers that:
119+
120+
- **Call external APIs** - GitHub, Slack, Notion, Linear, etc.
121+
- **Process data** - Text manipulation, calculations, transformations
122+
- **Search the web** - Brave Search, Exa, web scraping (headless)
123+
- **Interact with SaaS** - Any service with a public API
124+
- **Generate content** - Image generation, text processing
125+
126+
These MCP servers only need internet access and API credentials - both available on satellites.
127+
128+
## Quick Reference
129+
130+
| MCP Server Type | Global Satellite | Team Satellite | Local |
131+
|-----------------|------------------|----------------|-------|
132+
| GitHub, Slack, Notion |  |  |  |
133+
| External APIs |  |  |  |
134+
| Web scraping (headless) | � Requires setup |  |  |
135+
| Local SQLite files | L | L |  |
136+
| Local filesystem | L | L |  |
137+
| Internal databases | L |  |  |
138+
| Internal APIs | L |  |  |
139+
| Desktop automation | L | L |  |
140+
| Hardware access | L | L |  |
141+
142+
<Note>
143+
**Team Satellites** bridge the gap between convenience and local access. They run on your infrastructure but integrate with DeployStack's control plane for credential management and team governance.
144+
</Note>
145+
146+
---
147+
148+
**Need help deciding?** Join our [Discord community](https://discord.gg/42Ce3S7b3b) and we'll help you figure out what works best for your use case.

‎index.mdx‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -34,13 +34,21 @@ DeployStack is **The First MCP-as-a-Service Platform**. We solve two critical pr
3434
Host DeployStack on your own servers for complete control and security
3535
</Card>
3636

37-
<Card
38-
icon="shield"
39-
href="/security"
37+
<Card
38+
icon="shield"
39+
href="/security"
4040
title="Security & Governance"
4141
>
4242
Understand how DeployStack eliminates credential sprawl and provides enterprise security
4343
</Card>
44+
45+
<Card
46+
icon="circle-exclamation"
47+
href="/general/limitations"
48+
title="Platform Limitations"
49+
>
50+
Understand when global satellites work and when you need local MCP or team satellites
51+
</Card>
4452
</CardGroup>
4553

4654
## Developer Documentation

0 commit comments

Comments
 (0)