# How to Set Up MCP Server Configuration Files in jcode

> Learn to set up MCP server configuration files in jcode using JSON. Discover how jcode manages external tools via JSON-RPC 2.0 on stdio for efficient development.

- Repository: [Jeremy Huang/jcode](https://github.com/1jehuang/jcode)
- Tags: how-to-guide
- Published: 2026-04-30

---

**jcode** uses JSON configuration files at `~/.jcode/mcp.json` (global) or [`.jcode/mcp.json`](https://github.com/1jehuang/jcode/blob/main/.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/main/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`](https://github.com/1jehuang/jcode/blob/main/.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`](https://github.com/1jehuang/jcode/blob/main/.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`](https://github.com/1jehuang/jcode/blob/main/src/mcp/protocol.rs), each server entry requires at minimum a `command` field, with optional `args`, `env`, and `shared` fields.

```json
{
  "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/main/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/main/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:

```bash

# 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:

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

```

### Project-Local Setup

Place [`.jcode/mcp.json`](https://github.com/1jehuang/jcode/blob/main/.jcode/mcp.json) at your repository root for isolated tooling:

```json
{
  "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:

```bash
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`](https://github.com/1jehuang/jcode/blob/main/.jcode/mcp.json) to define MCP servers, loaded by `McpConfig::load()` in [`src/mcp/protocol.rs`](https://github.com/1jehuang/jcode/blob/main/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`](https://github.com/1jehuang/jcode/blob/main/src/mcp/mod.rs) spawns processes and registers tools as `mcp__<server>__<tool>`
- Use the `mcp` management tool (implemented in [`src/tool/mcp.rs`](https://github.com/1jehuang/jcode/blob/main/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`](https://github.com/1jehuang/jcode/blob/main/.jcode/mcp.json) in the current repository, then `~/.jcode/mcp.json` in the home directory, and finally compatibility fallbacks at [`.claude/mcp.json`](https://github.com/1jehuang/jcode/blob/main/.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`](https://github.com/1jehuang/jcode/blob/main/.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`](https://github.com/1jehuang/jcode/blob/main/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).