# Getting Started

## Prerequisites

- **Python 3.11+** -- [python.org/downloads](https://www.python.org/downloads/)
- **Node.js 18+** -- Required for MCP servers that use `npx` (Playwright, GitHub, etc.)
- **VS Code 1.96+** or **Cursor** -- For the extension UI

---

## Installation

### Option 1: uvx (Recommended -- No Install)

```bash
uvx mcp-grid
```

This runs MCP Grid directly without installing it into your Python environment.

### Option 2: pip

```bash
pip install mcp-grid
```

### Option 3: From Source (Development)

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

---

## Agent Configuration

### Cursor

Add to `~/.cursor/mcp.json`:

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

### Claude Desktop

Add to `claude_desktop_config.json`:

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

### Manual Run (Standalone)

```bash
# Start the bridge server
mcp-grid

# With debug logging
MCP_BRIDGE_LOG_LEVEL=DEBUG mcp-grid
```

---

## VS Code Extension

### Install

```bash
code --install-extension mcp-grid-studio.vsix
```

The extension automatically:
1. Starts the MCP Grid bridge server
2. Registers `mcp-grid` in Cursor's `mcp.json`
3. Connects the sidebar to the management API
4. Syncs the marketplace catalog

---

## First Agent Workflow

### Step 1: Discover Available Servers

```
discover_servers()
```

Returns categories and server counts. Browse a specific category:

```
discover_servers(category="browser-automation")
```

### Step 2: Configure a Server Instance

```
configure_server("playwright-mcp", config='{"headless": true, "browser": "chromium"}')
```

Returns an `instance_id` for subsequent calls.

### Step 3: Activate the Server

```
activate_server("abc123")
```

Starts the Playwright MCP server, discovers its 15 tools, and returns the list.

### Step 4: Use Tools

```
call_tool("abc123", "navigate", '{"url": "https://example.com"}')
```

Or run multiple tools in parallel:

```
parallel_call('[
  {"instance_id": "abc123", "tool_name": "navigate", "arguments": {"url": "https://a.com"}},
  {"instance_id": "def456", "tool_name": "get_issues", "arguments": {"repo": "org/repo"}}
]')
```

### Step 5: Clean Up

```
deactivate_server("abc123")
```

---

## OpenAPI Workflow

### Import a REST API

```
import_openapi_spec("https://petstore.swagger.io/v2/swagger.json")
```

### Browse Discovered Tools

```
list_api_tools("petstore")
```

### Configure Authentication

```
configure_api_auth("petstore", '{"ApiKeyAuth": "your-api-key"}')
```

### Call an Endpoint

```
call_api_tool("petstore", "getPetById", '{"petId": 1}')
```

---

## Adding Custom Servers

### Via YAML Catalog File

Create a file in `catalog/`:

```yaml
servers:
  - id: my-custom-server
    name: My Custom Server
    description: Does something awesome
    category: custom
    command: python
    args: ["-m", "my_server"]
    transport: stdio
    tags: ["custom"]
    configurable_options:
      - key: api_key
        label: API Key
        type: secret
        required: true
```

### Via Agent Import

```
import_mcp_config('{"mcpServers": {"my-server": {"command": "node", "args": ["server.js"]}}}')
```

### Via Management API

```bash
curl -X POST http://localhost:19420/api/servers \
  -H "Content-Type: application/json" \
  -d '{"id": "my-server", "name": "My Server", "command": "node", "args": ["server.js"]}'
```

---

## Configuration

All settings can be overridden via environment variables:

```bash
export MCP_BRIDGE_LOG_LEVEL=DEBUG
export MCP_BRIDGE_INSTANCE_IDLE_TIMEOUT_SECONDS=600
export MCP_BRIDGE_INSTANCE_MAX_TOTAL_INSTANCES=30
export MCP_BRIDGE_METRICS_ENABLED=false
```

See the [Technical Spec](../architecture/TECHNICAL_SPEC.md) for all available settings.

---

## Running Tests

```bash
pytest tests/ -v
```

---

## Troubleshooting

### Server won't start

1. Check the command is available: `which npx` or `which uvx`
2. Check required environment variables are set
3. Enable debug logging: `MCP_BRIDGE_LOG_LEVEL=DEBUG mcp-grid`
4. Check system resources: MCP Grid refuses new instances when CPU > 90% or memory > 80%

### Bridge not connected (extension)

1. Ensure `mcp-grid` Python package is installed
2. Check the bridge process is running: `ps aux | grep mcp`
3. Verify port 19420 is available: `lsof -i :19420`
4. Restart the extension: `Cmd+Shift+P` → `Developer: Reload Window`

### Tool call fails

1. Verify the instance is active: `get_server_status("instance-id")`
2. Check the tool name: `list_active_tools("instance-id")`
3. Verify arguments match the tool's input schema
4. Check the MCP server's own logs for errors
