mcp-grid 1.0.0rc1

A dynamic MCP server bridge - manage multiple MCP servers on demand without overloading agents

MCP Grid Studio

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

By IB-QA -- Intelligent Build & Quality Automation

---

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:

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.

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

# 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):

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

Claude Desktop (claude_desktop_config.json):

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

Install the VS Code Extension

# 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

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

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

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

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

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:

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

# 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 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 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	Connector and server manager patterns
mcp-use/mcp-use	Meta-tools pattern for lean agent context
universal-mcp/universal-mcp	Credential store abstraction and app registry
jlowin/fastmcp	The MCP framework MCP Grid is built on
CognitionAI/metabase-mcp-server	Tool categorization approach

License

MIT -- see LICENSE for details.

---

Built with care by IB-QA -- Intelligent Build & Quality Automation