mcp-grid 1.0.0rc1
A dynamic MCP server bridge - manage multiple MCP servers on demand without overloading agents
Requires Python: >=3.11
Keywords: agents, ai, automation, bridge, llm, mcp, model-context-protocol, tools

# MCP Grid Studio

> **The enterprise-grade MCP server orchestrator that turns any AI agent into a dynamic tool platform.**

**By [IB-QA](https://github.com/IB-QA)** -- Intelligent Build & Quality Automation

[![CI](https://github.com/IB-QA/McpServerStudio/actions/workflows/ci.yml/badge.svg)](https://github.com/IB-QA/McpServerStudio/actions)
[![PyPI](https://img.shields.io/pypi/v/mcp-grid)](https://pypi.org/project/mcp-grid/)
[![Python](https://img.shields.io/pypi/pyversions/mcp-grid)](https://pypi.org/project/mcp-grid/)
[![License](https://img.shields.io/github/license/IB-QA/McpServerStudio)](LICENSE)
[![Version](https://img.shields.io/badge/version-1.0.0--beta--rc-blue)](https://github.com/IB-QA/MCPServerGridStudio/releases)

---

## The Problem

Modern AI agents need access to dozens of tools -- browser automation, databases, APIs, code analysis, and more. But loading **every** tool from **every** MCP server at once creates serious issues:

```mermaid
graph LR
    A[AI Agent] -->|"100+ tools loaded"| B[Context Window]
    B -->|"Bloated"| C[❌ Poor tool selection]
    B -->|"Wasted"| D[❌ High token cost]
    B -->|"Idle processes"| E[❌ Resource waste]
    B -->|"Static config"| F[❌ No adaptability]
```

## The Solution

**MCP Grid Studio** is a meta-MCP server that sits between your AI agent and any number of MCP servers. It exposes **21 management tools** that let the agent dynamically discover, start, use, and stop servers on demand -- keeping the context window lean and resources efficient.

```mermaid
graph TB
    subgraph Agent["🤖 AI Agent (Cursor / Claude / etc.)"]
        direction LR
        AT["21 Meta-Tools"]
    end

    subgraph Grid["⚡ MCP Grid Studio"]
        direction TB
        LC["Local Server<br/>Management<br/>(9 tools)"]
        OA["OpenAPI-to-MCP<br/>Adapter<br/>(6 tools)"]
        EP["Enterprise Platform<br/>Integration<br/>(6 tools)"]
    end

    subgraph Instances["🔧 Dynamic Server Instances"]
        direction LR
        PW["Playwright"]
        GH["GitHub"]
        SQL["SQLite"]
        FS["Filesystem"]
        MORE["...more"]
    end

    subgraph APIs["🌐 REST APIs → MCP Tools"]
        direction LR
        API1["Stripe API"]
        API2["Jira API"]
        API3["Any OpenAPI"]
    end

    subgraph Enterprise["🏢 Enterprise Workflows"]
        direction LR
        WF1["Impact Analysis"]
        WF2["Code Review"]
        WF3["Custom Chains"]
    end

    subgraph Ext["📊 VS Code Extension"]
        SB["Sidebar"]
        DASH["Dashboard"]
        MKT["Marketplace"]
    end

    Agent -->|"MCP Protocol"| Grid
    LC --> Instances
    OA --> APIs
    EP -->|"WebSocket"| Enterprise
    Grid -->|"REST API"| Ext

    style Agent fill:#e8f4f8,stroke:#1a73e8
    style Grid fill:#f3e8ff,stroke:#7c3aed
    style Instances fill:#e8ffe8,stroke:#16a34a
    style APIs fill:#fff3e0,stroke:#ea580c
    style Enterprise fill:#fee2e2,stroke:#dc2626
    style Ext fill:#f0f9ff,stroke:#0284c7
```

## Key Features

| Feature | Description |
|---------|-------------|
| **Dynamic Lifecycle** | Servers start on demand and auto-shutdown when idle |
| **Context Efficiency** | Only 21 meta-tools in context; actual tools load dynamically |
| **Parallel Execution** | Multiple tool calls across instances run simultaneously |
| **Multi-Agent Isolation** | Each agent session gets its own isolated server instances |
| **Resource Guards** | CPU/memory checks prevent system overload |
| **OpenAPI Adapter** | Import any REST API spec and use endpoints as MCP tools |
| **Enterprise Workflows** | Execute workflow chains via WebSocket from the IDE |
| **Metrics Dashboard** | Track tool call counts, latency, success rates in real-time |
| **Verified Marketplace** | Curated catalog of security-verified MCP servers |
| **Tool Filtering** | Whitelist/blacklist tools per server per user |
| **Health Monitoring** | Auto-restart crashed servers, periodic health checks |
| **Config Import** | Import from `mcp.json`, GitHub repos, or OpenAPI specs |
| **Zero Credential Persistence** | All tokens in-memory only -- nothing written to disk |

---

## Quick Start

### Install

```bash
# Recommended: via uvx (no install needed)
uvx mcp-grid

# Or via pip
pip install mcp-grid

# Or from source
git clone https://github.com/IB-QA/McpServerStudio.git
cd McpServerStudio
pip install -e ".[dev]"
```

### Add to Your AI Agent

**Cursor** (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "mcp-grid": {
      "command": "uvx",
      "args": ["mcp-grid"]
    }
  }
}
```

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "mcp-grid": {
      "command": "uvx",
      "args": ["mcp-grid"]
    }
  }
}
```

### Install the VS Code Extension

```bash
# From .vsix (download from Releases)
code --install-extension mcp-grid-studio.vsix

# Or search "MCP Grid" in VS Code Marketplace (coming soon)
```

---

## Agent Workflows

### Local MCP Server Lifecycle

```mermaid
sequenceDiagram
    participant A as AI Agent
    participant G as MCP Grid
    participant S as Server Instance

    A->>G: discover_servers(category="browser")
    G-->>A: [{id: "playwright-mcp", tools: 15, ...}]

    A->>G: configure_server("playwright-mcp", {headless: true})
    G-->>A: {instance_id: "abc123"}

    A->>G: activate_server("abc123")
    G->>S: Start process + discover tools
    S-->>G: [navigate, click, screenshot, ...]
    G-->>A: {status: "active", tools: [...]}

    A->>G: call_tool("abc123", "navigate", {url: "..."})
    G->>S: Forward tool call
    S-->>G: Tool result
    G-->>A: {success: true, result: ...}

    A->>G: deactivate_server("abc123")
    G->>S: Terminate process
    G-->>A: {status: "stopped"}
```

### OpenAPI-to-MCP Adapter Flow

```mermaid
sequenceDiagram
    participant A as AI Agent
    participant G as MCP Grid
    participant API as REST API

    A->>G: import_openapi_spec("https://api.stripe.com/openapi.json")
    G-->>A: {api_id: "stripe", tools_discovered: 48}

    A->>G: list_api_tools("stripe")
    G-->>A: [{name: "createCharge", method: "POST", ...}, ...]

    A->>G: configure_api_auth("stripe", {BearerAuth: "sk-..."})
    G-->>A: {configured: true}

    A->>G: call_api_tool("stripe", "createCharge", {amount: 2000})
    G->>API: POST /v1/charges {amount: 2000}
    API-->>G: {id: "ch_xxx", status: "succeeded"}
    G-->>A: {success: true, result: ...}
```

### Enterprise Workflow Execution

```mermaid
sequenceDiagram
    participant A as AI Agent
    participant G as MCP Grid
    participant WS as Enterprise Platform (WebSocket)

    A->>G: connect_platform({url: "...", jwt: "..."})
    G->>WS: Open WebSocket + authenticate
    WS-->>G: Connected
    G-->>A: {connected: true}

    A->>G: list_workflows()
    G-->>A: [{id: "uuid", title: "Impact Analysis", ...}]

    A->>G: execute_workflow("uuid", {query: "Analyze work items"})
    G->>WS: SendMessageV2 payload
    WS-->>G: answer chunks (streaming)
    WS-->>G: tool_use_request → tool_use_response
    WS-->>G: agent_execution_stats
    G-->>A: {result: "...", stats: {cycles: 10, duration: 78s}}

    A->>G: disconnect_platform()
    G->>WS: Close connection
    G-->>A: {disconnected: true}
```

---

## 21 Meta-Tools Reference

### Local MCP Server Management (9 tools)

| # | Tool | Parameters | Description |
|---|------|-----------|-------------|
| 1 | `discover_servers` | `category?`, `search_query?`, `tag?` | Browse the server catalog by category, keyword, or tag |
| 2 | `configure_server` | `server_id`, `config?`, `session_id?` | Create a configured instance ready for activation |
| 3 | `activate_server` | `instance_id` | Start the server process and discover available tools |
| 4 | `call_tool` | `instance_id`, `tool_name`, `arguments?` | Execute a tool on an active server instance |
| 5 | `deactivate_server` | `instance_id` | Stop a server and free all resources |
| 6 | `get_server_status` | `instance_id` | Get instance state, uptime, tool count, call stats |
| 7 | `list_active_tools` | `instance_id?` | List all tools across all (or one) active instance |
| 8 | `parallel_call` | `calls` (array) | Execute multiple tool calls across instances simultaneously |
| 9 | `import_mcp_config` | `config_json` | Import servers from standard `mcp.json` format |

### OpenAPI-to-MCP Adapter (6 tools)

| # | Tool | Parameters | Description |
|---|------|-----------|-------------|
| 10 | `import_openapi_spec` | `spec_source`, `api_name?` | Import OpenAPI 3.x / Swagger 2.0 from URL, file, or raw JSON |
| 11 | `list_api_tools` | `api_name` | Browse all discovered API endpoints as callable tools |
| 12 | `configure_api_auth` | `api_name`, `auth_config` | Set auth: API Key, Bearer Token, Basic Auth, or OAuth2 |
| 13 | `customize_api_tool` | `api_name`, `tool_name`, `changes` | Rename, re-describe, or disable auto-generated tools |
| 14 | `call_api_tool` | `api_name`, `tool_name`, `arguments?` | Execute an API endpoint as an MCP tool call |
| 15 | `get_api_tool_schema` | `api_name`, `tool_name` | Get full JSON Schema for a tool's input parameters |

### Enterprise Platform Integration (6 tools)

| # | Tool | Parameters | Description |
|---|------|-----------|-------------|
| 16 | `connect_platform` | `platform_url`, `jwt_token` | Connect to an enterprise AI platform via JWT |
| 17 | `list_workflows` | `search?`, `owned_by_me?` | Browse available workflow chains with optional filters |
| 18 | `get_workflow_details` | `workflow_id` | Inspect chain components, input variables, and config |
| 19 | `execute_workflow` | `workflow_id`, `query`, `params?` | Run a workflow chain via WebSocket, get full results |
| 20 | `get_platform_status` | -- | Check connection health and token validity |
| 21 | `disconnect_platform` | -- | Disconnect and clear all tokens from memory |

---

## Pre-Built Server Catalog

| Category | Server | Transport | Key Config Options |
|----------|--------|-----------|-------------------|
| **Browser & Automation** | Playwright MCP | stdio (`npx`) | `headless`, `browser`, `viewport` |
| | Puppeteer MCP | stdio (`npx`) | `headless`, `viewport` |
| **Data & Analytics** | SQLite MCP | stdio (`uvx`) | `db_path` |
| | PostgreSQL MCP | stdio (`npx`) | `connection_string` |
| **Development** | GitHub MCP | stdio (`npx`) | `GITHUB_TOKEN` (env) |
| | Git MCP | stdio (`uvx`) | -- |
| | Filesystem MCP | stdio (`npx`) | `allowed_directories` |
| **Search & Web** | Brave Search MCP | stdio (`npx`) | `BRAVE_API_KEY` (env) |
| | Fetch MCP | stdio (`uvx`) | -- |
| **Utilities** | Time MCP | stdio (`uvx`) | -- |
| | Memory MCP | stdio (`npx`) | -- |

Add your own via YAML catalog files, `import_mcp_config`, or the OpenAPI adapter.

---

## Architecture

### System Architecture

```mermaid
graph TB
    subgraph IDE["IDE Layer"]
        Agent["AI Agent<br/>(Cursor / Claude Desktop)"]
        Ext["VS Code Extension<br/>(Sidebar + Dashboard + Marketplace)"]
    end

    subgraph Bridge["MCP Grid Bridge Server"]
        direction TB
        Server["FastMCP Server Entry Point<br/>(server.py)"]
        
        subgraph Tools["Meta-Tools Layer"]
            MT["meta_tools.py<br/>(9 local tools)"]
            OAT["openapi/tools.py<br/>(6 OpenAPI tools)"]
            PT["platforms/platform_tools.py<br/>(6 enterprise tools)"]
        end

        subgraph Core["Core Services"]
            REG["Server Registry<br/>(SQLite + YAML)"]
            IM["Instance Manager<br/>(Process Pool)"]
            TP["Tool Proxy<br/>(Namespace Routing)"]
            MC["Metrics Collector<br/>(SQLite)"]
            CS["Credential Store<br/>(Memory / Env)"]
        end

        subgraph Adapters["Protocol Adapters"]
            OAP["OpenAPI Parser<br/>(3.x / Swagger 2.0)"]
            OAE["OpenAPI Executor<br/>(HTTP Client)"]
            WSA["WebSocket Adapter<br/>(Platform Connector)"]
            TM["Token Manager<br/>(In-Memory Only)"]
        end

        API["Management REST API<br/>(Starlette + WebSocket)"]
    end

    subgraph Servers["Server Instances (On-Demand)"]
        S1["Playwright<br/>(stdio)"]
        S2["GitHub<br/>(stdio)"]
        S3["SQLite<br/>(stdio)"]
        S4["Custom<br/>(http)"]
    end

    subgraph External["External Services"]
        REST["REST APIs<br/>(OpenAPI specs)"]
        ENT["Enterprise Platform<br/>(WebSocket)"]
    end

    Agent <-->|"MCP Protocol<br/>(stdio/http)"| Server
    Server --> Tools
    MT --> Core
    OAT --> Adapters
    PT --> Adapters
    IM --> Servers
    OAE --> REST
    WSA --> ENT
    API <-->|"REST + WS"| Ext

    style IDE fill:#e8f4f8,stroke:#1a73e8
    style Bridge fill:#f3e8ff,stroke:#7c3aed
    style Servers fill:#e8ffe8,stroke:#16a34a
    style External fill:#fff3e0,stroke:#ea580c
```

### Server Instance Lifecycle

```mermaid
stateDiagram-v2
    [*] --> Registered: YAML / import / API
    Registered --> Configured: configure_server()
    Configured --> Starting: activate_server()
    Starting --> Active: Tools discovered
    Starting --> Failed: Startup error
    Active --> Active: call_tool()
    Active --> Idle: No calls for N seconds
    Idle --> Active: New call arrives
    Idle --> ShuttingDown: Auto-shutdown
    Active --> ShuttingDown: deactivate_server()
    ShuttingDown --> Stopped: Process terminated
    Failed --> Configured: Retry
    Stopped --> [*]
```

### Project Structure

```
McpServerStudio/
├── src/mcp_bridge/
│   ├── server.py                    # FastMCP entry point (21 tools registered)
│   ├── meta_tools.py                # 9 local server management tools
│   ├── config/
│   │   └── settings.py              # Pydantic BaseSettings + env overrides
│   ├── registry/
│   │   ├── catalog.py               # Server CRUD (SQLite + YAML)
│   │   └── models.py                # ServerEntry, InstanceInfo data models
│   ├── instances/
│   │   ├── manager.py               # Instance lifecycle, resource guards
│   │   └── connector.py             # MCP connection (stdio / HTTP)
│   ├── credentials/
│   │   └── store.py                 # Memory, Env, Composite credential stores
│   ├── metrics/
│   │   └── collector.py             # Tool call recording (SQLite)
│   ├── api/
│   │   └── management.py            # REST + WebSocket for extension
│   ├── openapi/
│   │   ├── parser.py                # OpenAPI 3.x / Swagger 2.0 parser
│   │   ├── executor.py              # HTTP request builder + executor
│   │   ├── models.py                # OpenAPI spec, operation, auth models
│   │   └── tools.py                 # 6 OpenAPI meta-tools
│   └── platforms/
│       ├── platform_tools.py        # 6 enterprise platform meta-tools
│       ├── websocket_adapter.py     # WebSocket executor (open-send-recv-close)
│       ├── auth/
│       │   └── token_manager.py     # In-memory token lifecycle
│       ├── models/
│       │   ├── workflow.py           # Workflow, Component models
│       │   └── messages.py           # WebSocket message types
│       └── workflow/
│           └── executor.py           # Workflow discovery + execution
├── catalog/                         # Pre-built server definitions (YAML)
│   ├── browser-automation.yaml
│   ├── data-analytics.yaml
│   ├── development.yaml
│   ├── search-web.yaml
│   └── utilities.yaml
├── extension/                       # VS Code / Cursor extension (TypeScript)
│   ├── src/
│   │   ├── extension.ts             # Activation entry point
│   │   ├── bridge/
│   │   │   ├── client.ts            # Bridge management API client
│   │   │   └── autoSetup.ts         # Auto-register in mcp.json
│   │   ├── providers/
│   │   │   ├── serversTreeProvider.ts
│   │   │   ├── instancesTreeProvider.ts
│   │   │   ├── metricsTreeProvider.ts
│   │   │   └── marketplaceTreeProvider.ts
│   │   ├── panels/
│   │   │   ├── dashboardPanel.ts     # Metrics dashboard webview
│   │   │   └── addServerPanel.ts     # Add server wizard webview
│   │   ├── services/
│   │   │   ├── secretStore.ts        # VS Code SecretStorage wrapper
│   │   │   ├── authFlow.ts           # OAuth2 / SSO / PAT auth flows
│   │   │   └── catalogSync.ts        # Marketplace hourly sync
│   │   └── commands/
│   │       └── index.ts              # Command registrations
│   └── package.json
├── marketplace-site/                # Marketplace website (deploys to gh-pages)
│   ├── static/index.html
│   ├── build_catalog.py
│   └── output/catalog.json
├── docs/                            # Internal documentation
│   ├── architecture/
│   │   ├── OVERVIEW.md
│   │   └── TECHNICAL_SPEC.md
│   ├── enterprise/
│   │   └── ENTERPRISE_AI_PLATFORM_INTEGRATION.md
│   ├── guides/
│   │   ├── GETTING_STARTED.md
│   │   └── PUBLISHING.md
│   └── REFERENCES.md
├── tests/
├── pyproject.toml
└── .github/workflows/
    ├── ci.yml
    ├── release.yml
    └── deploy-marketplace.yml
```

---

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `MCP_BRIDGE_LOG_LEVEL` | `INFO` | Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`) |
| `MCP_BRIDGE_DATA_DIR` | `~/.mcp-bridge` | Data directory for SQLite databases |
| `MCP_BRIDGE_INSTANCE_MAX_TOTAL_INSTANCES` | `20` | Maximum concurrent server instances |
| `MCP_BRIDGE_INSTANCE_MAX_INSTANCES_PER_SERVER` | `5` | Max instances of the same server |
| `MCP_BRIDGE_INSTANCE_MAX_INSTANCES_PER_AGENT` | `10` | Max instances per agent session |
| `MCP_BRIDGE_INSTANCE_STARTUP_TIMEOUT_SECONDS` | `30` | Timeout for server startup |
| `MCP_BRIDGE_INSTANCE_IDLE_TIMEOUT_SECONDS` | `300` | Auto-shutdown idle servers after N seconds |
| `MCP_BRIDGE_SYSTEM_MAX_MEMORY_PERCENT` | `80` | Refuse new instances above this memory % |
| `MCP_BRIDGE_SYSTEM_MAX_CPU_PERCENT` | `90` | Refuse new instances above this CPU % |
| `MCP_BRIDGE_METRICS_ENABLED` | `true` | Enable/disable local metrics collection |
| `MCP_BRIDGE_METRICS_RETENTION_DAYS` | `30` | Days to retain metrics before cleanup |
| `MCP_BRIDGE_API_HOST` | `127.0.0.1` | Management API bind address (localhost only) |
| `MCP_BRIDGE_API_PORT` | `19420` | Management API port |

### VS Code Extension Settings

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

---

## Metrics & Performance Dashboard

MCP Grid Studio tracks performance metrics for every tool call across all servers:

```mermaid
graph LR
    subgraph Collected["📊 Data Collected (Local Only)"]
        TC["Tool Call Counts<br/>(success / failure)"]
        LT["Latency<br/>(avg, p50, p95)"]
        SE["Server Events<br/>(start / stop / error)"]
    end

    subgraph Dashboard["📈 Extension Dashboard"]
        SC["Success Rate Charts"]
        LP["Latency per Server"]
        TT["Top Tools Ranking"]
        TL["Activity Timeline"]
    end

    subgraph NOT["🚫 NOT Collected"]
        NC1["Tool call content"]
        NC2["Arguments / results"]
        NC3["User data"]
        NC4["Credentials"]
    end

    Collected --> Dashboard
    NOT -.->|"Never stored"| Dashboard

    style NOT fill:#fee2e2,stroke:#dc2626
    style Collected fill:#e8ffe8,stroke:#16a34a
```

All metrics are stored locally in SQLite. Nothing is sent externally. Collection can be disabled via `MCP_BRIDGE_METRICS_ENABLED=false` or the extension settings toggle.

---

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Lint
ruff check src/

# Format
ruff format src/

# Type check
mypy src/

# Build extension
cd extension && npm install && npm run compile

# Package extension
cd extension && npx vsce package
```

---

## Publishing

See [docs/guides/PUBLISHING.md](docs/guides/PUBLISHING.md) for detailed instructions on:

- Publishing the Python package to PyPI
- Publishing the VS Code extension to the Marketplace
- Creating GitHub Releases
- Setting up CI/CD secrets

---

## Roadmap

See the [public roadmap](https://github.com/IB-QA/MCPServerGridStudio/wiki/Roadmap) for upcoming features:

- **MCP Grid Studio Desktop App** -- Standalone desktop tool for creating and managing MCP servers without an IDE
- **No-Code MCP Server Creator** -- AI-assisted wizard to create MCP servers from natural language descriptions
- **JetBrains Plugin** -- IntelliJ IDEA, PyCharm, WebStorm support
- **Visual Studio Extension** -- Full VS (not just VS Code) support
- **Community Marketplace** -- Publish and share your own MCP servers
- **Advanced Benchmarking** -- MCP-Bench inspired performance profiling

---

## Acknowledgements & Inspiration

| Project | Inspiration Taken |
|---------|------------------|
| [Accenture/mcp-bench](https://github.com/Accenture/mcp-bench) | Connector and server manager patterns |
| [mcp-use/mcp-use](https://github.com/mcp-use/mcp-use) | Meta-tools pattern for lean agent context |
| [universal-mcp/universal-mcp](https://github.com/universal-mcp/universal-mcp) | Credential store abstraction and app registry |
| [jlowin/fastmcp](https://github.com/jlowin/fastmcp) | The MCP framework MCP Grid is built on |
| [CognitionAI/metabase-mcp-server](https://github.com/CognitionAI/metabase-mcp-server) | Tool categorization approach |

## License

MIT -- see [LICENSE](LICENSE) for details.

---

Built with care by **[IB-QA](https://github.com/IB-QA)** -- Intelligent Build & Quality Automation