# How to Configure MCP Server Settings in ChatMCP Using `mcp_server.json`

> Learn to configure MCP server settings in ChatMCP using mcp_server.json. Manage server definitions via file editing, UI, or programmatically with McpServerProvider for seamless integration.

- Repository: [刀刀/chatmcp](https://github.com/daodao97/chatmcp)
- Tags: how-to-guide
- Published: 2026-02-28

---

**ChatMCP stores all MCP server definitions in a JSON file named [`mcp_server.json`](https://github.com/daodao97/chatmcp/blob/main/mcp_server.json) located in the application data directory, which initializes from [`assets/mcp_server.json`](https://github.com/daodao97/chatmcp/blob/main/assets/mcp_server.json) on first launch and supports manual editing, UI-based configuration, or programmatic management through the `McpServerProvider` class.**

The `daodao97/chatmcp` repository implements a centralized configuration system for Model Context Protocol (MCP) servers through a dedicated JSON file. Understanding the schema, location, and manipulation methods for [`mcp_server.json`](https://github.com/daodao97/chatmcp/blob/main/mcp_server.json) enables you to connect local command-line tools, remote HTTP endpoints, and OAuth-protected services to your ChatMCP environment.

## Understanding the [`mcp_server.json`](https://github.com/daodao97/chatmcp/blob/main/mcp_server.json) Schema

The configuration file maintains a single top-level key, **`mcpServers`**, whose value is an object mapping server names to their configuration parameters. This structure is enforced by the provider logic in `lib/provider/mcp_server_provider.dart`.

### Server Configuration Fields

Each server entry accepts the following properties:

- **`type`** – Connection protocol. Valid values are `sse`, `stdio`, `streamable`, or `inmemory`.
- **`command`** – The executable command for local servers or the URL for remote endpoints.
- **`args`** – Array of command-line arguments passed to the server process.
- **`env`** – Object containing environment variables as key-value pairs.
- **`auto_approve`** – Boolean flag. When `true`, ChatMCP skips manual confirmation prompts for generated content.
- **`oauth`** – Optional authentication block containing `enabled`, `client_id`, `authorization_url`, `token_url`, `scope`, `redirect_uri`, `access_token`, `refresh_token`, and `token_expiry`.

Example structure for an SSE server with OAuth:

```json
{
  "mcpServers": {
    "MyServer": {
      "type": "sse",
      "command": "http://localhost:8000",
      "args": [],
      "env": {},
      "auto_approve": false,
      "oauth": {
        "enabled": true,
        "client_id": "abc123",
        "authorization_url": "https://example.com/auth",
        "token_url": "https://example.com/token",
        "scope": "read write",
        "redirect_uri": "https://your-app.com/oauth_callback.html",
        "access_token": "...",
        "refresh_token": "...",
        "token_expiry": "2026-03-30T12:00:00Z"
      }
    }
  }
}

```

## Configuration File Location and Initialization

ChatMCP resolves the configuration path using `StorageManager.getAppDataDirectory()` defined in `lib/utils/storage_manager.dart`. Platform-specific locations include:

- **Windows:** `%AppData%/ChatMCP/mcp_server.json`
- **macOS:** `~/Library/Application Support/ChatMCP/mcp_server.json`

On application startup, the `_initConfigFile` method (lines 49-60 in `lib/provider/mcp_server_provider.dart`) verifies file existence. If missing, it copies the default template from [`assets/mcp_server.json`](https://github.com/daodao97/chatmcp/blob/main/assets/mcp_server.json) (declared in [`pubspec.yaml`](https://github.com/daodao97/chatmcp/blob/main/pubspec.yaml) line 113) to the app-data directory, ensuring a valid starting configuration.

## Three Methods to Configure MCP Servers

ChatMCP exposes three distinct interfaces for modifying server settings, accommodating manual editing, graphical interaction, and programmatic automation.

### Method 1: Manual File Editing

Directly edit `[AppDataDirectory]/mcp_server.json` using any text editor. After saving changes, restart ChatMCP or reload the provider to apply modifications. This method offers immediate access to all JSON fields, including OAuth tokens not exposed in the UI.

### Method 2: Settings UI

The graphical interface implemented in `lib/page/setting/mcp_server.dart` (lines 22-30) provides form-based server management. When you add or modify servers, the UI invokes `McpServerProvider.addMcpServer`, `removeMcpServer`, or `saveServers` to persist changes. For URLs requiring authentication, the `_checkOAuthRequirement` method (lines 50-66) triggers automatic OAuth discovery.

### Method 3: Programmatic Configuration

Obtain the singleton provider instance and manipulate configurations through Dart code. The `McpServerProvider` class exposes type-safe methods that handle JSON serialization, validation, and prettified file output (lines 89-106 in `lib/provider/mcp_server_provider.dart`).

## OAuth Auto-Discovery

When connecting to endpoints requiring authentication, ChatMCP automates OAuth configuration through the `discoverOAuthForServer` method. This process contacts the server's well-known metadata endpoint, constructs an `OAuthDiscoveryResult`, and populates the `oauth` block in [`mcp_server.json`](https://github.com/daodao97/chatmcp/blob/main/mcp_server.json) after user confirmation. This eliminates manual token entry and ensures schema compliance with the provider's expectations.

## Implementation Examples

### Loading Current Configuration

Retrieve the active configuration map using the provider's `loadServers` method:

```dart
final provider = McpServerProvider();               // singleton
final config = await provider.loadServers();        // → Map<String, dynamic>
print(config['mcpServers']);

```

### Adding a Server Programmatically

Create a server definition and persist it through the provider:

```dart
final newServer = {
  'name': 'LocalMcp',
  'type': 'sse',
  'command': 'http://127.0.0.1:5000',
  'args': [],
  'env': {'DEBUG': '1'},
  'auto_approve': true,
};

await provider.addMcpServer(newServer);
// UI refreshes automatically because the provider notifies listeners.

```

### Modifying Existing Settings

Update specific fields and save back to disk:

```dart
final all = await provider.loadServers();
final servers = all['mcpServers'] as Map<String, dynamic>;
final server = servers['LocalMcp'] as Map<String, dynamic>;

server['command'] = 'http://127.0.0.1:6000';
await provider.saveServers(all);   // writes back to mcp_server.json

```

### Removing a Server

Delete entries using the server name:

```dart
await provider.removeMcpServer('LocalMcp');

```

### Direct File Access

For desktop platforms, manipulate the file directly using Dart's I/O libraries:

```dart
import 'package:chatmcp/utils/storage_manager.dart';
import 'dart:io';
import 'dart:convert';

final dir = await StorageManager.getAppDataDirectory();
final file = File('${dir.path}/mcp_server.json');

// Load, modify, save
final map = json.decode(await file.readAsString()) as Map<String, dynamic>;
map['mcpServers']?['MyServer']?['auto_approve'] = true;
await file.writeAsString(const JsonEncoder.withIndent('  ').convert(map));

```

## Summary

- **[`mcp_server.json`](https://github.com/daodao97/chatmcp/blob/main/mcp_server.json)** resides in the app-data directory (`StorageManager.getAppDataDirectory()`) and initializes from [`assets/mcp_server.json`](https://github.com/daodao97/chatmcp/blob/main/assets/mcp_server.json) if absent
- The JSON structure requires a top-level **`mcpServers`** object containing server definitions with `type`, `command`, and optional `oauth` fields
- Configuration changes propagate through **`McpServerProvider`** methods (`loadServers`, `addMcpServer`, `saveServers`, `removeMcpServer`) defined in `lib/provider/mcp_server_provider.dart`
- Three editing approaches exist: direct file manipulation, Settings UI (`lib/page/setting/mcp_server.dart`), or programmatic Dart code
- OAuth settings auto-populate via **`discoverOAuthForServer`** when using authenticated endpoints, preventing manual token entry errors

## Frequently Asked Questions

### Where is [`mcp_server.json`](https://github.com/daodao97/chatmcp/blob/main/mcp_server.json) located on different operating systems?

The file path resolves through `StorageManager.getAppDataDirectory()` in `lib/utils/storage_manager.dart`. On Windows, this maps to `%AppData%/ChatMCP/mcp_server.json`; on macOS, to `~/Library/Application Support/ChatMCP/mcp_server.json`. Linux environments follow the XDG specification for application data directories.

### What happens if [`mcp_server.json`](https://github.com/daodao97/chatmcp/blob/main/mcp_server.json) is deleted or corrupted?

If the file is missing when ChatMCP starts, the `_initConfigFile` method (lines 49-60 in `lib/provider/mcp_server_provider.dart`) automatically copies the default empty configuration from [`assets/mcp_server.json`](https://github.com/daodao97/chatmcp/blob/main/assets/mcp_server.json) to the app-data directory. This ensures the application remains functional with an empty server list, which you can then populate.

### How do I enable automatic approval for server-generated content?

Set the **`auto_approve`** field to `true` within the specific server configuration object. This can be configured through the Settings UI toggle or by editing the JSON field directly in [`mcp_server.json`](https://github.com/daodao97/chatmcp/blob/main/mcp_server.json). When enabled, ChatMCP bypasses confirmation prompts for that server's generated content, streamlining automation workflows for trusted local services.

### Can I manually configure OAuth settings without using the auto-discovery flow?

While you can manually construct the **`oauth`** object in [`mcp_server.json`](https://github.com/daodao97/chatmcp/blob/main/mcp_server.json), the recommended approach uses the **`discoverOAuthForServer`** method through the Settings UI. Manual configuration requires precise ISO 8601 timestamps for `token_expiry` and valid endpoint URLs, whereas auto-discovery validates against the server's OAuth metadata endpoint and ensures the schema matches the provider's expectations in `lib/provider/mcp_server_provider.dart`.