> ## Documentation Index
> Fetch the complete documentation index at: https://ibm-d95bab6e.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# VSCode (Copilot Chat)

> Configure IBM i MCP Server with VSCode through GitHub Copilot Chat

# VSCode Integration

Visual Studio Code supports MCP servers through GitHub Copilot Chat. You can configure servers at the workspace or user level, enabling your entire team to share MCP configurations.

<Note>
  **Prerequisites**:

  * VSCode 1.102+ with [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) installed and enabled
  * Copilot subscription (individual, business, or enterprise)
  * MCP support is generally available from VS Code 1.102
</Note>

## Configuration File Locations

<Tabs>
  <Tab title="Workspace">
    **Location**: `.vscode/mcp.json` in your project root

    **Benefits**:

    * Shared with team via version control
    * Project-specific MCP servers
    * Consistent across team members

    ```bash theme={null}
    mkdir -p .vscode
    touch .vscode/mcp.json
    ```
  </Tab>

  <Tab title="User">
    **Recommended Method**: Use Command Palette

    1. Press `Cmd/Ctrl+Shift+P`
    2. Run **MCP: Open User Configuration**
    3. Edit in VSCode with IntelliSense support

    **File Locations** (if editing manually):

    * **macOS/Linux**: `~/.config/Code/User/globalStorage/modelcontextprotocol.mcp/mcp.json`
    * **Windows**: `%APPDATA%\Code\User\globalStorage\modelcontextprotocol.mcp\mcp.json`

    **Benefits**:

    * Available across all projects
    * Personal configuration
    * Not shared via version control
  </Tab>
</Tabs>

## Local (Stdio) Setup

### Using Command Palette (Recommended)

1. Press `Cmd/Ctrl+Shift+P`
2. Run **MCP: Add Server**
3. Choose **Workspace** or **Global** scope
4. Paste configuration and edit with IntelliSense

### Using CLI

```bash theme={null}
# Add local stdio server
code --add-mcp '{
  "name": "ibmiMcp",
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@ibm/ibmi-mcp-server@latest", "--tools", "/absolute/path/to/tools"],
  "env": {
    "DB2i_HOST": "your-ibmi-host.com",
    "DB2i_USER": "your-username",
    "DB2i_PASS": "your-password",
    "DB2i_PORT": "8076",
    "MCP_TRANSPORT_TYPE": "stdio"
  }
}'
```

### Using mcp.json

Create or edit `mcp.json`:

```json theme={null}
{
  "servers": {
    "ibmiMcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@ibm/ibmi-mcp-server@latest", "--tools", "/absolute/path/to/tools"],
      "env": {
        "DB2i_HOST": "your-ibmi-host.com",
        "DB2i_USER": "your-username",
        "DB2i_PASS": "your-password",
        "DB2i_PORT": "8076",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}
```

<Warning>
  **Important**: The `--tools` path must be an **absolute path**.
</Warning>

<Info>
  **Security**: On first start, VSCode will prompt you to trust the MCP server. Only trust servers from reliable sources as they can execute code on your machine.
</Info>

## Remote (HTTP/SSE) Setup

VSCode supports both HTTP and SSE (Server-Sent Events) transport for remote servers.

### Using CLI

```bash theme={null}
# Add remote HTTP server
code --add-mcp '{
  "name": "ibmiMcp",
  "type": "http",
  "url": "http://localhost:3010/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
  }
}'
```

### Using mcp.json

<Tabs>
  <Tab title="HTTP Transport">
    ```json theme={null}
    {
      "servers": {
        "ibmiMcp": {
          "type": "http",
          "url": "http://localhost:3010/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="SSE Transport">
    ```json theme={null}
    {
      "servers": {
        "ibmiMcp": {
          "type": "sse",
          "url": "http://localhost:3010/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
          }
        }
      }
    }
    ```

    <Info>
      **SSE (Server-Sent Events)**: Alternative to HTTP transport for real-time server updates. Use when your server supports SSE protocol.
    </Info>
  </Tab>
</Tabs>

## Secure Credentials with Variables

VSCode supports multiple variable types for secure credential management and flexible configurations:

### Input Variables

Prompt users for sensitive data at runtime:

```json theme={null}
{
  "inputs": [
    {
      "id": "db2iHost",
      "type": "promptString",
      "description": "IBM i DB2 host address"
    },
    {
      "id": "db2iUser",
      "type": "promptString",
      "description": "IBM i username"
    },
    {
      "id": "db2iPass",
      "type": "promptString",
      "description": "IBM i password",
      "password": true
    }
  ],
  "servers": {
    "ibmiMcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@ibm/ibmi-mcp-server@latest", "--tools", "/absolute/path/to/tools"],
      "env": {
        "DB2i_HOST": "${input:db2iHost}",
        "DB2i_USER": "${input:db2iUser}",
        "DB2i_PASS": "${input:db2iPass}",
        "DB2i_PORT": "8076",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}
```

<Tip>
  VSCode will prompt for these values when the server starts, keeping credentials secure and out of version control.
</Tip>

### Built-in Variables

Use VSCode's built-in variables for dynamic paths:

* **`${workspaceFolder}`** - Absolute path to the workspace root
* **`${env:VAR_NAME}`** - Environment variable value
* **`${userHome}`** - User's home directory path

**Example:**

```json theme={null}
{
  "servers": {
    "ibmiMcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@ibm/ibmi-mcp-server@latest", "--tools", "${workspaceFolder}/tools"],
      "env": {
        "DB2i_HOST": "${env:IBM_HOST}",
        "DB2i_USER": "${env:IBM_USER}",
        "DB2i_PASS": "${env:IBM_PASS}"
      }
    }
  }
}
```

<Tip>
  **Best Practice**: Use `${workspaceFolder}` for tools paths in team configs so they work regardless of where teammates clone the repo.
</Tip>

## Managing Servers

### List All Servers

1. Open Command Palette (`Cmd/Ctrl+Shift+P`)
2. Run **MCP: List Servers**
3. View all configured servers with status

### View Servers in Chat

* Open the **Copilot Chat** view in the Activity Bar
* Look for MCP servers listed in the chat interface
* Click the MCP indicator to see available tools

### Restart Server

**Method 1 - Command Palette:**

1. Press `Cmd/Ctrl+Shift+P`
2. Run **MCP: Restart Server**
3. Select your server from the list

**Method 2 - Extensions View:**

* Right-click server in Extensions view
* Select "Restart"

### Autostart Servers (Experimental)

Enable automatic server startup:

1. Open VSCode Settings
2. Search for `chat.mcp.autostart`
3. Enable the setting

### Disable Server

Remove or comment out the server entry in `mcp.json`

## Testing the Connection

After configuration:

1. **Reload VSCode**: `Cmd/Ctrl+Shift+P` → "Developer: Reload Window"
2. **Open Copilot Chat**: Click the chat icon in Activity Bar
3. **Check MCP status**: Look for MCP indicator in Copilot Chat
4. **List tools**: Ask "@mcp what tools are available?"
5. **Test a tool**: Ask "Show me the IBM i system status"

## Troubleshooting

<AccordionGroup>
  <Accordion title="MCP Server Not Appearing">
    **Solutions**:

    * Verify JSON syntax in `mcp.json`
    * Reload VSCode window: `Cmd/Ctrl+Shift+P` → "Developer: Reload Window"
    * Check Copilot is installed and enabled
    * Verify GitHub Copilot subscription is active
    * Look for errors in Output panel: View → Output → "MCP"
  </Accordion>

  <Accordion title="Server Fails to Start">
    **Solutions**:

    * Verify `npx -y @ibm/ibmi-mcp-server@latest` works from terminal
    * Check all paths are absolute
    * Ensure IBM i credentials are correct
    * Review VSCode Developer Tools: Help → Toggle Developer Tools
  </Accordion>

  <Accordion title="Authentication Failed (Remote)">
    **Solutions**:

    * Verify remote server is running
    * Check token is valid and not expired
    * Ensure correct Authorization header format
    * Get fresh token: `node get-access-token.js --verbose`
  </Accordion>

  <Accordion title="Input Variables Not Prompting">
    **Solutions**:

    * Ensure `inputs` array is at root level of `mcp.json`
    * Verify `${input:id}` syntax is correct
    * Restart VSCode completely
    * Check that input IDs match between definition and usage
  </Accordion>
</AccordionGroup>

## Advanced Configuration

### Team Workspace Setup

Share MCP configuration with your team via `.vscode/mcp.json`:

```json theme={null}
{
  "inputs": [
    {
      "id": "db2iHost",
      "type": "promptString",
      "description": "IBM i host (e.g., dev-ibmi.company.com)",
      "default": "dev-ibmi.company.com"
    },
    {
      "id": "db2iUser",
      "type": "promptString",
      "description": "Your IBM i username"
    },
    {
      "id": "db2iPass",
      "type": "promptString",
      "description": "Your IBM i password",
      "password": true
    }
  ],
  "servers": {
    "ibmiMcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["@ibm/ibmi-mcp-server@latest", "-y", "--tools", "${workspaceFolder}/tools"],
      "env": {
        "DB2i_HOST": "${input:db2iHost}",
        "DB2i_USER": "${input:db2iUser}",
        "DB2i_PASS": "${input:db2iPass}",
        "DB2i_PORT": "8076",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}
```

### Multiple Environments

Configure dev and prod servers:

```json theme={null}
{
  "servers": {
    "ibmi-dev": {
      "type": "stdio",
      "command": "npx",
      "args": ["@ibm/ibmi-mcp-server@latest", "-y", "--tools", "/path/to/dev-tools"],
      "env": {
        "DB2i_HOST": "dev-ibmi.company.com",
        "DB2i_USER": "${input:devUser}",
        "DB2i_PASS": "${input:devPass}",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    },
    "ibmi-prod": {
      "type": "http",
      "url": "https://prod-mcp.company.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:PROD_MCP_TOKEN}"
      }
    }
  }
}
```

### Custom Toolsets

Load specific toolsets for different workflows:

```json theme={null}
{
  "servers": {
    "ibmi-performance": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "@ibm/ibmi-mcp-server@latest", "-y",
        "--tools", "/path/to/tools",
        "--toolsets", "performance,monitoring"
      ],
      "env": {
        "DB2i_HOST": "your-ibmi-host.com",
        "DB2i_USER": "${input:db2iUser}",
        "DB2i_PASS": "${input:db2iPass}",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="SQL Tools" icon="database" href="/sql-tools/overview">
    Create custom SQL tools for your workflows
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration">
    Explore all configuration options
  </Card>

  <Card title="Authentication" icon="lock" href="/configuration#ibm-i-authentication-settings">
    Set up secure IBM i authentication
  </Card>

  <Card title="Other Clients" icon="grid" href="/clients/overview">
    Explore other MCP-compatible clients
  </Card>
</CardGroup>

## Additional Resources

* [VSCode MCP Documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
* [GitHub Copilot Marketplace](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot)
* [IBM i MCP Quick Start](/quickstart)