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

ChatMCP stores all MCP server definitions in a JSON file named mcp_server.json located in the application data directory, which initializes from 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 enables you to connect local command-line tools, remote HTTP endpoints, and OAuth-protected services to your ChatMCP environment.

Understanding the 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:

{
  "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 (declared in 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 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:

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:

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:

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:

await provider.removeMcpServer('LocalMcp');

Direct File Access

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

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 resides in the app-data directory (StorageManager.getAppDataDirectory()) and initializes from 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 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 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 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. 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}