How to Set Up MCP Server Configuration Files in jcode

jcode uses JSON configuration files at ~/.jcode/mcp.json (global) or .jcode/mcp.json (project-local) to declare MCP servers, which are loaded via McpConfig::load() and managed by the McpManager to expose external tools via JSON-RPC 2.0 on stdio.

The Model Context Protocol (MCP) enables jcode to communicate with external processes such as local LLM servers or filesystem browsers. According to the 1jehuang/jcode source code, the server process maintains a shared pool of MCP connections that all client sessions can access, configured through standalone JSON files decoupled from the main application settings.

Configuration File Locations and Precedence

jcode discovers MCP server configuration files through a hierarchical lookup that merges multiple locations with specific precedence rules. When the server starts, it invokes McpConfig::load() in [src/mcp/protocol.rs](https://github.com/1jehuang/jcode/blob/master/src/mcp/protocol.rs) to read and merge these sources:

• Project-local: .jcode/mcp.json in the repository root takes highest precedence
• Global: ~/.jcode/mcp.json applies across all projects for the user
• Compatibility fallbacks: .claude/mcp.json or ~/.codex/config.toml are respected on first run for migration from older clients

The loader merges these locations in reverse order, meaning project-local settings override global ones, ensuring repository-specific tools remain isolated.

JSON Configuration Schema

Each configuration file must contain a top-level servers object mapping server names to their launch parameters. According to the schema defined in src/mcp/protocol.rs, each server entry requires at minimum a command field, with optional args, env, and shared fields.

{
  "servers": {
    "filesystem": {
      "command": "/usr/local/bin/mcp-filesystem",
      "args": ["--root", "/workspace"],
      "env": {
        "MCP_LOG": "debug"
      },
      "shared": true
    },
    "my-llm": {
      "command": "/opt/llm/run.sh",
      "args": ["--model", "gemma-2b"],
      "env": {}
    }
  }
}

The shared boolean (defaulting to true) determines whether the server process is pooled for reuse across sessions.

Loading and Managing MCP Servers

After loading the configuration, jcode instantiates an McpManager (see [src/mcp/mod.rs](https://github.com/1jehuang/jcode/blob/master/src/mcp/mod.rs)) which handles the server lifecycle:

1. Spawns each process using the specified command, args, and env
2. Registers tools with the jcode tool registry under the naming convention mcp__<server>__<tool>
3. Exposes management actions through the built-in mcp tool implemented in [src/tool/mcp.rs](https://github.com/1jehuang/jcode/blob/master/src/tool/mcp.rs)

This architecture decouples MCP servers from the main jcode configuration, enabling hot-reloading without restarting the daemon.

CLI Management Commands

You can interact with running MCP servers through the mcp management tool from the TUI or command line:

# List currently connected MCP servers

jcode mcp '{"action":"list"}'

# Connect a new server dynamically

jcode mcp '{"action":"connect","server":"myfs","command":"/usr/local/bin/mcp-server","args":["--root","/my/workspace"]}'

# Disconnect a specific server

jcode mcp '{"action":"disconnect","server":"myfs"}'

# Reload configuration from JSON files

jcode mcp '{"action":"reload"}'

The reload action unloads all previously registered MCP tools and recreates them from the current JSON files, allowing seamless updates to your MCP server configuration files during development.

Practical Configuration Examples

Minimal Global Configuration

Create ~/.jcode/mcp.json for tools available across all projects:

{
  "servers": {
    "filesystem": {
      "command": "/usr/local/bin/mcp-filesystem",
      "args": [],
      "env": {},
      "shared": true
    }
  }
}

Project-Local Setup

Place .jcode/mcp.json at your repository root for isolated tooling:

{
  "servers": {
    "my-llm": {
      "command": "./scripts/start-llm.sh",
      "args": ["--port", "8080"],
      "env": {
        "LLM_API_KEY": "my-token"
      }
    }
  }
}

Runtime Connection

Add servers without editing configuration files:

jcode mcp '{
  "action":"connect",
  "server":"experimental",
  "command":"./debug-mcp.sh",
  "args":["--verbose"]
}'

Summary

• jcode uses external JSON files at ~/.jcode/mcp.json or .jcode/mcp.json to define MCP servers, loaded by McpConfig::load() in src/mcp/protocol.rs
• Configuration follows a precedence hierarchy: project-local overrides global settings
• Each server requires a command field with optional args, env, and shared parameters
• The McpManager in src/mcp/mod.rs spawns processes and registers tools as mcp__<server>__<tool>
• Use the mcp management tool (implemented in src/tool/mcp.rs) to list, connect, disconnect, or reload servers without restarting the jcode daemon

Frequently Asked Questions

Where does jcode look for MCP server configuration files?

jcode searches three locations in order of precedence: first .jcode/mcp.json in the current repository, then ~/.jcode/mcp.json in the home directory, and finally compatibility fallbacks at .claude/mcp.json or ~/.codex/config.toml. The McpConfig::load() function merges these sources, with project-local settings taking priority over global ones.

What is the difference between global and project-local MCP configs?

Global configuration at ~/.jcode/mcp.json makes MCP servers available to every jcode project on your machine, while project-local .jcode/mcp.json restricts servers to a specific repository. This isolation allows teams to ship custom MCP tools with their codebase without affecting other projects or user-wide settings.

How do I reload MCP configuration without restarting jcode?

Execute jcode mcp '{"action":"reload"}' to trigger the reload mechanism in src/tool/mcp.rs. This unloads all existing MCP tools and re-creates them from the current JSON configuration files, enabling hot-updates to server definitions, environment variables, or arguments while the jcode server process continues running.

What fields are required in the MCP server JSON configuration?

Each entry under the servers object must include a command string specifying the executable path. All other fields are optional: args (array of command-line arguments), env (object of environment variables), and shared (boolean, defaults to true to enable connection pooling across sessions).

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