# Snow CLI User Documentation - MCP Configuration

Welcome to Snow CLI! Agentic coding in your terminal.

## MCP Configuration

MCP (Model Context Protocol) is an open protocol that allows AI assistants to integrate with external tools and services. Snow CLI supports configuring and managing MCP services.

### What is MCP

MCP (Model Context Protocol) is a standardized protocol for connecting AI assistants with various external tools, data sources, and services. Through MCP, Snow CLI can access local file systems, connect to databases, call external APIs, and more.

### View MCP Service Status

Enter the `/mcp` command in the chat interface to view the status of all MCP services:

**Display Content**:

- Service name
- Connection status (green ● for connected, red ● for failed, gray ● for disabled)
- Service type (System/External/Disabled)
- Available tools list

**Operations**:

- **Up/Down arrows**: Navigate through service list
- **Enter key**: Reconnect selected service
- **Tab key**: Toggle enable/disable for external services (not supported for built-in services)
- Select "Refresh all services" option to refresh all services

### Configure MCP Services

#### 1. Enter Configuration Interface

Select `MCP Configuration` from the main menu to enter the MCP configuration editor.

You will first choose a configuration scope:

- **Project Config**: writes to `.snow/settings.json` under the current working directory (`mcpServers` field)
- **Global Config**: writes to `~/.snow/settings.json` (`mcpServers` field)

#### 2. Automatic Editor Detection

The system will automatically detect and use an appropriate text editor to open a draft config file; after you save, the result is written back into the corresponding `settings.json` for that scope:

**Editor Priority**:

1. Editor specified by `VISUAL` environment variable
2. Editor specified by `EDITOR` environment variable
3. System default editor

**Windows**: Detection order: notepad++ > notepad > code > vim > nano

**macOS/Linux**: Detection order: nano > vim > vi

**Set Default Editor**:

macOS/Linux:

```bash
export EDITOR=nano
```

Windows:

```cmd
set EDITOR=notepad
```

#### 3. Configuration Locations and Priority

MCP configuration now lives under the `mcpServers` field of `settings.json`. The standalone `mcp-config.json` file is no longer used (legacy files are migrated on startup).

| Scope   | Path                            | Applies to           |
| ------- | ------------------------------- | -------------------- |
| Project | `<project>/.snow/settings.json` | Current project only |
| Global  | `~/.snow/settings.json`         | All projects         |

**Merge rules**:

- Runtime loads and merges global + project MCP servers
- **Project wins**: for the same server name, project-level config overrides global
- Put repo-specific MCP servers in project settings; put shared ones in global settings

You can also edit these files directly without using the UI.

#### 4. Configuration File Format

**Configuration Structure** (same for project and global):

```json
{
	"mcpServers": {
		"service-name": {
			"command": "command",
			"args": ["arg1", "arg2"],
			"enabled": true
		}
	}
}
```

> **Note**: `settings.json` may already contain other settings (for example `yoloMode`, `disabledSkills`). When adding MCP servers, read the existing file first and **merge** into `mcpServers` instead of overwriting the whole file.

**Configuration Options**:

- `mcpServers`: MCP service configuration object
- `service-name`: Custom service name (unique identifier)
- `type`: Transport type, optional values are `'stdio'`, `'local'`, `'http'`, `'sse'`, or `'api'` (optional, auto-detected based on `url` or `command` by default)
  - `'stdio'`: Local subprocess communication (STDIO mode)
  - `'local'`: Alias for `'stdio'`, functionally identical
  - `'http'`: HTTP mode for connecting to remote MCP services
  - `'sse'`: SSE mode (also carried over HTTP, for legacy SSE services)
  - `'api'`: Custom API mode, mapping plain HTTP endpoints to MCP tools (fully compatible with the "API" MCP type in Snow APP)
- `command`: Command to start the MCP service (required for `stdio`/`local` type)
- `args`: Command argument array (optional; for the `api` type it may hold a `{cookies, endpoints}` spec object to match the Snow APP database format)
- `url`: MCP service endpoint URL (required for `http` type; the Base URL for the `api` type)
- `headers`: HTTP request headers configuration (optional for `http` / `api` type)
- `cookies`: Shared cookies (optional, `api` type only)
- `endpoints`: Endpoint definitions (required for the `api` type; each endpoint becomes one MCP tool)
- `enabled`: Whether to enable the service (optional, defaults to true)
- `timeout`: Tool invocation timeout in milliseconds (optional, defaults to 1200000, i.e., 20 minutes)
- `env` / `environment`: Environment variables configuration (optional), `environment` is an alias for `env`

**Configuration Example**:

**Project-level example** (`<project>/.snow/settings.json`):

```json
{
	"yoloMode": false,
	"mcpServers": {
		"project-docs": {
			"type": "stdio",
			"command": "npx",
			"args": ["-y", "@modelcontextprotocol/server-filesystem", "./docs"],
			"enabled": true
		}
	}
}
```

**STDIO/Local Mode Example**:

```json
{
	"mcpServers": {
		"filesystem": {
			"type": "stdio",
			"command": "npx",
			"args": [
				"-y",
				"@modelcontextprotocol/server-filesystem",
				"/path/to/files"
			],
			"timeout": 600000
		},
		"github": {
			"type": "local",
			"command": "npx",
			"args": ["-y", "@modelcontextprotocol/server-github"],
			"enabled": true,
			"environment": {
				"GITHUB_TOKEN": "your_token_here"
			}
		}
	}
}
```

**HTTP Mode Example**:

```json
{
	"mcpServers": {
		"remote-service": {
			"type": "http",
			"url": "https://api.example.com/mcp",
			"headers": {
				"Authorization": "Bearer ${API_KEY}",
				"X-Custom-Header": "custom-value"
			},
			"env": {
				"API_KEY": "your_api_key_here"
			},
			"timeout": 1200000
		}
	}
}
```

> **Note**: HTTP mode supports reading configuration values from environment variables using the `${VAR_NAME}` syntax.

**Custom API Mode Example**:

The `api` type needs no subprocess or MCP handshake: Snow CLI calls the configured `endpoints` over HTTP directly and exposes each endpoint as an MCP tool. The format matches the "API" MCP type in Snow APP (you can paste the JSON exported by the APP; the APP database format `args: {cookies, endpoints}` is also recognized).

```json
{
	"mcpServers": {
		"DeepSeekSearch": {
			"type": "api",
			"url": "https://api.deepseek.com",
			"headers": {
				"Authorization": "Bearer your_api_key_here"
			},
			"endpoints": [
				{
					"name": "WebSearch",
					"description": "Web search",
					"method": "POST",
					"path": "/v1/tools/search",
					"headers": {},
					"params": [
						{
							"name": "query",
							"type": "string",
							"required": true,
							"description": "Search query",
							"location": "body",
							"defaultValue": ""
						},
						{
							"name": "count",
							"type": "integer",
							"required": true,
							"description": "Number of results",
							"location": "body",
							"defaultValue": "10"
						}
					],
					"bodyType": "json",
					"bodyTemplate": "{\n  \"query\": \"{{query}}\",\n  \"count\": \"{{count}}\"\n}"
				}
			]
		}
	}
}
```

**Endpoint fields**:

- `name`: Tool name (defaults to `endpoint_<index>`)
- `description`: Tool description used by the model to decide when to call it
- `method` / `path`: HTTP method and path relative to the Base URL; the path supports `{{param}}` placeholders (URL-component encoded)
- `headers`: Endpoint-level request headers (merged with top-level `headers`; endpoint-level wins on conflicts)
- `params`: Parameter list
  - `location`: `query`, `path`, `header`, or `body` — where the parameter is sent
  - `type`: `string`, `number`, `integer`, `boolean`, `object`, or `array`
  - `required`: Whether it is required (the model may omit it when `defaultValue` is set)
  - `defaultValue`: Applied automatically when the caller omits the parameter
- `bodyType`: `none`, `json`, `form`, `multipart`, or `raw`
- `bodyTemplate`: Request body template; `{{param}}` placeholders are replaced (a placeholder that stands alone inside JSON keeps its original type, and missing optional parameters are removed from the body)
- `rawContentType`: Content-Type for a `raw` body (defaults to `text/plain`)

### Configuration Validation

After saving the configuration file, the system will automatically validate it:

**Success Message** (includes the selected scope name):

```text
Project Config MCP configuration saved successfully! Please use `snow` restart!
```

**Error Message**:

```text
Invalid JSON format. Changes have been reverted to the previous valid configuration.
```

### Using MCP Services

After configuration, restart Snow CLI for changes to take effect:

```bash
snow
```

After startup, use the `/mcp` command to view service connection status.

### Manage MCP Services

#### Enable/Disable Services

**Method 1: Edit Configuration File**

Set the `enabled` field to `false` to disable a service

**Method 2: Use /mcp Command**

1. Enter `/mcp` to open the service panel
2. Use up/down arrows to select service
3. Press Tab key to toggle enable/disable status

**Note**:

- The **Tab toggle** in the `/mcp` panel is mainly for external MCP servers
- Some built-in tool services can be disabled via `disabledBuiltInServices` (for example `snow-docs`)
- Example in `<project>/.snow/settings.json`:

```json
{
	"disabledBuiltInServices": ["snow-docs"]
}
```

For the built-in official docs tools (`snow-docs-list` / `snow-docs-search` / `snow-docs-get`), see: [Official Docs Tools (snow-docs)](./28.Official%20Docs%20Tools%20snow-docs.md).

#### Reconnect Services

In the `/mcp` panel, select a service and press Enter to reconnect

### Troubleshooting

#### 1. Editor Cannot Open

**Error Message**:

```text
No text editor found! Please set the EDITOR or VISUAL environment variable.
```

**Solution**:

Set environment variable or install a text editor:

macOS/Linux:

```bash
export EDITOR=nano
```

Windows:

```cmd
set EDITOR=notepad
```

#### 2. Service Connection Failed

**Check Items**:

1. Is the command path correct
2. Are dependencies installed (e.g., Node.js for npx)
3. Is the parameter format correct
4. Use `/mcp` to view specific error messages

#### 3. Configuration Not Taking Effect

**Solution**:

1. Confirm configuration file is saved
2. Restart Snow CLI
3. Use `/mcp` to check service status

### Related Resources

- MCP Official Documentation: <https://modelcontextprotocol.io>
- MCP Services Repository: <https://github.com/modelcontextprotocol>
- Command Guide: [Command Panel Guide](./09.0.Command%20Panel%20Guide.md)
- Built-in official docs tools: [Official Docs Tools (snow-docs)](./28.Official%20Docs%20Tools%20snow-docs.md)