# MCP Configuration Reference
This document explains the MCP server configuration for different environments.
## VS Code Copilot Configuration
VS Code with GitHub Copilot uses **two configuration files**:
### 1. `.vscode/mcp.json` (Primary - Required!)
This is the **main configuration file** that VS Code Copilot reads:
```json
{
"hackernews": {
"command": "node",
"args": ["${workspaceFolder}/dist/index.js"],
"env": {
"DEBUG": "0"
}
}
}
```
**Key points:**
- Located at `.vscode/mcp.json` in your workspace
- Each key (e.g., "hackernews") is a server name
- `${workspaceFolder}` is replaced with your workspace path
- `env.DEBUG` controls logging level ("0" = info, "1" = debug)
### 2. `.vscode/settings.json` (Optional - Enhanced Features)
Additional VS Code settings for MCP:
```json
{
"github.copilot.chat.mcp.enabled": true,
"github.copilot.chat.mcp.servers": {
"hackernews": {
"command": "node",
"args": ["dist/index.js"],
"cwd": "${workspaceFolder}",
"env": {
"DEBUG": "0"
}
}
}
}
```
**Key points:**
- Enables MCP explicitly
- Can provide additional configuration
- `cwd` sets working directory
## Configuration Fields
### Required Fields
- **`command`**: The executable to run (e.g., "node", "python", "/usr/bin/node")
- **`args`**: Array of command-line arguments
### Optional Fields
- **`env`**: Environment variables as key-value pairs
- **`cwd`**: Working directory (defaults to workspace folder)
### VS Code Variables
You can use these VS Code variables in your configuration:
- `${workspaceFolder}` - Root folder of the workspace
- `${workspaceFolderBasename}` - Name of workspace folder
- `${file}` - Currently open file
- `${fileBasename}` - Basename of currently open file
- `${fileDirname}` - Directory of currently open file
## Debug Mode
### Enable Debug Logging
Update the `env` section:
```json
{
"hackernews": {
"command": "node",
"args": ["${workspaceFolder}/dist/index.js"],
"env": {
"DEBUG": "1"
}
}
}
```
### View Logs
1. Open VS Code Output panel (`Ctrl+Shift+U`)
2. Select "GitHub Copilot Chat" from dropdown
3. Look for MCP-related messages
## Testing Your Configuration
### 1. Build the Server
```bash
npm run build
```
Verify `dist/index.js` exists.
### 2. Reload VS Code
Press `Ctrl+Shift+P` → "Developer: Reload Window"
### 3. Check Copilot Chat
Open Copilot Chat and ask:
```
What MCP tools are available?
```
You should see the HackerNews tools listed.
### 4. Test a Tool
Try a simple query:
```
Show me the top HN stories
```
## Alternative Configurations
### Global Installation
If you install the server globally:
```bash
npm link
```
You can use a simpler configuration:
```json
{
"hackernews": {
"command": "hn-mcp-server"
}
}
```
### Absolute Paths
Instead of `${workspaceFolder}`, you can use absolute paths:
```json
{
"hackernews": {
"command": "node",
"args": ["/home/user/projects/hn-mcp-server/dist/index.js"]
}
}
```
### Custom Node.js Path
If you use a specific Node.js version:
```json
{
"hackernews": {
"command": "/usr/local/bin/node",
"args": ["${workspaceFolder}/dist/index.js"]
}
}
```
Or with nvm:
```json
{
"hackernews": {
"command": "/home/user/.nvm/versions/node/v20.10.0/bin/node",
"args": ["${workspaceFolder}/dist/index.js"]
}
}
```
## Claude Desktop Configuration
Claude Desktop uses a different configuration file.
**Location:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/claude/claude_desktop_config.json`
**Format:**
```json
{
"mcpServers": {
"hackernews": {
"command": "node",
"args": ["/absolute/path/to/hn-mcp-server/dist/index.js"]
}
}
}
```
**Note:** Claude Desktop requires **absolute paths** (no variables).
## Troubleshooting
### Tools Not Appearing
1. Check `.vscode/mcp.json` exists and is valid JSON
2. Verify `dist/index.js` exists (run `npm run build`)
3. Reload VS Code (`Ctrl+Shift+P` → "Developer: Reload Window")
4. Check for errors in Output panel
### Server Not Starting
1. Test the server manually:
```bash
node dist/index.js
```
Should output: `"HN MCP Server started successfully"`
2. Check Node.js version:
```bash
node --version
```
Should be v20.0.0 or higher
3. Verify file permissions:
```bash
ls -la dist/index.js
```
### Rate Limit Errors
The HN API has a 10,000 requests/hour limit. If you hit it:
- Wait for the hourly reset
- Check rate limit usage in debug logs
- Reduce query frequency
## Example Configurations
### Development Setup
```json
{
"hackernews": {
"command": "node",
"args": ["${workspaceFolder}/dist/index.js"],
"env": {
"DEBUG": "1",
"NODE_ENV": "development"
}
}
}
```
### Production Setup
```json
{
"hackernews": {
"command": "hn-mcp-server",
"env": {
"DEBUG": "0",
"NODE_ENV": "production"
}
}
}
```
### Multiple Servers
You can configure multiple MCP servers:
```json
{
"hackernews": {
"command": "node",
"args": ["${workspaceFolder}/dist/index.js"]
},
"another-server": {
"command": "python",
"args": ["/path/to/another/server.py"]
}
}
```
## Best Practices
1. **Use workspace variables** - Makes config portable
2. **Keep DEBUG=0 in production** - Reduces log noise
3. **Test manually first** - Run `node dist/index.js` before configuring
4. **Use absolute paths for Claude Desktop** - No variable support
5. **Reload after changes** - VS Code needs reload to pick up config changes
---
**Need help?** See [VSCODE_SETUP.md](VSCODE_SETUP.md) for detailed setup instructions.
