# MCP Grid Studio -- VS Code Extension

**Dynamic MCP Server Bridge Manager for VS Code & Cursor**

MCP Grid Studio is an enterprise-grade extension for monitoring, configuring, and controlling multiple MCP servers on demand -- without overloading your AI agent's context window.

---

## Features

### Sidebar Panels

```
┌────────────────────────────────┐
│  MCP GRID                      │
│  ════════════════              │
│                                │
│  ▼ Servers                     │  ← Installed servers + tools
│    ├ 📦 Playwright MCP         │
│    │  ├ 🔧 navigate            │
│    │  ├ 🔧 click               │
│    │  └ 🔧 screenshot          │
│    ├ 📦 GitHub MCP             │
│    └ 📦 SQLite MCP             │
│                                │
│  ▼ Active Instances            │  ← Running server processes
│    ├ ⚡ pw-abc123 (active)     │
│    │  ├ 15 tools loaded        │
│    │  └ 23 calls, 0 errors     │
│    └ ⚡ gh-def456 (active)     │
│                                │
│  ▼ Metrics                     │  ← Aggregate performance
│    ├ Total Calls: 183          │
│    ├ Success Rate: 97%         │
│    └ Avg Latency: 142ms        │
│                                │
│  ▼ Marketplace                 │  ← Browse + install servers
│    ├ 🌐 Browser & Automation   │
│    │  ├ Playwright MCP [Install]│
│    │  └ Puppeteer MCP [Install]│
│    ├ 📊 Data & Analytics       │
│    └ 🔧 Development            │
└────────────────────────────────┘
```

### Performance Dashboard (Webview)

```
┌─────────────────────────────────────────────────────────────────┐
│  MCP Grid Dashboard                                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐       │
│  │ Active   │  │ Total    │  │ Success  │  │ Avg      │       │
│  │ Instances│  │ Calls    │  │ Rate     │  │ Latency  │       │
│  │    3     │  │   183    │  │   97%    │  │  142ms   │       │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘       │
│                                                                  │
│  Per-Server Performance                                          │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │ Server        │ Calls  │ Latency  │ Success │ Errors    │   │
│  │───────────────│────────│──────────│─────────│───────────│   │
│  │ Playwright    │   48   │  230ms   │   96%   │    2      │   │
│  │ GitHub        │   23   │   89ms   │  100%   │    0      │   │
│  │ SQLite        │  112   │   12ms   │   99%   │    1      │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                  │
│  Recent Activity                                                 │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │ 09:14:32  navigate     pw-abc123  ✓  230ms              │   │
│  │ 09:14:30  get_issues   gh-def456  ✓   89ms              │   │
│  │ 09:14:28  query        sq-ghi789  ✓   12ms              │   │
│  │ 09:14:25  screenshot   pw-abc123  ✓  540ms              │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
```

### Add Server Wizard (Webview)

Three tabs for different server types:

```
┌──────────────────────────────────────────────────────────────┐
│  Add MCP Server                                               │
├──────────────────────────────────────────────────────────────┤
│  [Manual]  [OpenAPI / Swagger]  [WebSocket / Platform]        │
│  ═══════                                                      │
│                                                               │
│  Manual Tab:                                                  │
│    Server Name, Command, Args, Transport, Category, Env Vars  │
│                                                               │
│  OpenAPI Tab:                                                 │
│    Spec URL or file path, API name, Auth type                 │
│                                                               │
│  WebSocket Tab:                                               │
│    Platform URL, JWT token, WebSocket endpoint                │
│                                                               │
│              [Cancel]  [Add Server]                            │
└──────────────────────────────────────────────────────────────┘
```

---

## 21 Agent Tools

MCP Grid exposes 21 tools to your AI agent, organized in three groups:

| # | Tool | Group | Description |
|---|------|-------|-------------|
| 1 | `discover_servers` | Local | Browse available servers |
| 2 | `configure_server` | Local | Set up an instance |
| 3 | `activate_server` | Local | Start + discover tools |
| 4 | `call_tool` | Local | Execute a tool |
| 5 | `deactivate_server` | Local | Stop + free resources |
| 6 | `get_server_status` | Local | Check instance state |
| 7 | `list_active_tools` | Local | List loaded tools |
| 8 | `parallel_call` | Local | Multi-tool parallel execution |
| 9 | `import_mcp_config` | Local | Import from mcp.json |
| 10 | `import_openapi_spec` | OpenAPI | Import REST API spec |
| 11 | `list_api_tools` | OpenAPI | Browse API endpoints |
| 12 | `configure_api_auth` | OpenAPI | Set API credentials |
| 13 | `customize_api_tool` | OpenAPI | Rename/describe tools |
| 14 | `call_api_tool` | OpenAPI | Execute API endpoint |
| 15 | `get_api_tool_schema` | OpenAPI | Get input schema |
| 16 | `connect_platform` | Enterprise | Connect via JWT |
| 17 | `list_workflows` | Enterprise | Browse workflows |
| 18 | `get_workflow_details` | Enterprise | Inspect chain |
| 19 | `execute_workflow` | Enterprise | Run via WebSocket |
| 20 | `get_platform_status` | Enterprise | Check connection |
| 21 | `disconnect_platform` | Enterprise | Disconnect + clear |

---

## Commands

| Command | Description |
|---------|-------------|
| `MCP Grid: Open Dashboard` | Open the metrics dashboard webview |
| `MCP Grid: Add Server (Manual)` | Open the Add Server wizard |
| `MCP Grid: Add Server (OpenAPI)` | Open Add Server with OpenAPI tab |
| `MCP Grid: Configure Server` | Configure an installed server |
| `MCP Grid: Refresh Servers` | Refresh the servers tree view |
| `MCP Grid: Refresh Marketplace` | Refresh marketplace catalog |
| `MCP Grid: Register in MCP Config` | Add MCP Grid to Cursor's mcp.json |

---

## Installation

### Prerequisites

- **Python 3.11+** with `mcp-grid` package installed
- **VS Code 1.96+** or **Cursor**

### Install the Extension

```bash
# From .vsix file
code --install-extension mcp-grid-studio.vsix

# From VS Code Marketplace (coming soon)
# Search "MCP Grid" in Extensions
```

### Install the Python Backend

```bash
# Recommended
uvx mcp-grid

# Or via pip
pip install mcp-grid
```

### Auto-Setup

On first activation, the extension:

1. Starts the MCP Grid bridge server
2. Registers `mcp-grid` as an MCP server in `~/.cursor/mcp.json`
3. Connects the sidebar UI to the management API
4. Syncs the marketplace catalog

---

## Configuration

| Setting | Default | Description |
|---------|---------|-------------|
| `mcpGrid.bridgeHost` | `127.0.0.1` | Bridge API host |
| `mcpGrid.bridgePort` | `19420` | Bridge API port |
| `mcpGrid.autoStart` | `true` | Auto-start bridge on activation |
| `mcpGrid.pythonPath` | `python3` | Python interpreter |
| `mcpGrid.pollingInterval` | `5000` | Fallback polling interval (ms) |
| `mcpGrid.metricsEnabled` | `true` | Enable local metrics collection |
| `mcpGrid.metricsRetentionDays` | `30` | Metrics retention period |

---

## Security

- **In-memory credentials** -- API keys and tokens stored in VS Code SecretStorage (OS keychain)
- **No disk persistence** -- No `.env` files, no token caches created
- **Localhost only** -- Management API binds to `127.0.0.1`
- **XSS protection** -- All webview content HTML-escaped with CSP headers
- **No telemetry** -- No data sent externally

---

## Data Collection

The extension collects only anonymous, local performance metrics:

| Collected | NOT Collected |
|-----------|--------------|
| Tool call counts | Tool call content |
| Latency (ms) | Arguments or results |
| Success/failure | User identity |
| Server events | Credentials |

All data stays on your machine. Collection can be disabled in settings.

---

## License

MIT -- [IB-QA](https://github.com/IB-QA)
