Forem: Lukas Wolfsteiner

One MCP Configuration for Codex, Claude, Cursor, and Copilot with chezmoi

Lukas Wolfsteiner — Sat, 07 Mar 2026 21:11:08 +0000

If you use multiple coding agents across multiple machines, MCP configuration drift is unavoidable unless you make one file the source of truth.

This guide shows a practical setup for:

Codex
Claude Code
Cursor
GitHub Copilot (including VS Code and Copilot coding agent scenarios)

The core idea is simple:

Keep one canonical MCP manifest in your chezmoi source state.
Generate each tool's native config format from that manifest.
Let chezmoi manage symlinks/templates and machine-specific values.

Why this works

All four tools model MCP servers with the same conceptual fields:

Server name
Transport type (stdio vs remote HTTP/SSE-like)
Command + args + env for local servers
URL + headers/auth for remote servers

What differs is file location and schema shape.

So instead of manually editing four formats, you maintain one normalized model and project it into each target file.

What each tool expects today

Codex

Codex stores MCP inside config.toml, typically at ~/.codex/config.toml, with optional project overrides in .codex/config.toml for trusted projects.

MCP entries are under [mcp_servers.<name>] and support both local command servers and remote URL servers.

Claude Code

Claude settings are split across ~/.claude/settings.json, .claude/settings.json, and .claude/settings.local.json, but MCP server configuration is associated with ~/.claude.json for user/local scope and .mcp.json for project scope.

In practice, you can treat .mcp.json as the repository-shareable MCP surface and keep secrets/user-only material outside repo.

Cursor

Cursor uses JSON with mcpServers and supports command- and URL-based MCP installations.

The official docs page confirms MCP as a first-class feature and transport diversity; path specifics (~/.cursor/mcp.json, .cursor/mcp.json) are consistent with the validated storage map you linked.

GitHub Copilot / VS Code

There are two adjacent configuration worlds:

VS Code MCP config: mcp.json (workspace commonly at .vscode/mcp.json, plus user profile config)
Copilot coding agent MCP config: JSON with mcpServers and explicit type (local, stdio, http, sse), and documented reuse from VS Code MCP configuration patterns

For a chezmoi setup, it is practical to generate:

.vscode/mcp.json for local editor agent workflows
.copilot/mcp-config.json (or equivalent copilot-target file in your model) for coding-agent workflows where needed

Common ground: a normalized MCP model

Use one canonical data file, for example in chezmoi source state:

dot_config/mcp/servers.yaml

servers:
  github:
    transport: http
    url: "https://api.githubcopilot.com/mcp/"
    headers:
      Authorization: "Bearer ${GITHUB_TOKEN}"

  filesystem:
    transport: stdio
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/lukas"]
    env:
      NODE_NO_WARNINGS: "1"

Then render adapters per tool.

chezmoi layout that scales

A practical structure:

~/.local/share/chezmoi/
  .chezmoitemplates/
    mcp/
      codex-config.toml.tmpl
      claude-mcp.json.tmpl
      cursor-mcp.json.tmpl
      vscode-mcp.json.tmpl
      copilot-mcp-config.json.tmpl
  dot_config/
    mcp/
      servers.yaml
  dot_codex/
    config.toml.tmpl
  dot_claude/
    mcp_servers.json.tmpl
  dot_cursor/
    mcp.json.tmpl
  dot_vscode/
    mcp.json.tmpl
  dot_copilot/
    mcp-config.json.tmpl

Use .chezmoitemplates for reusable snippets and avoid duplicating mapping logic.

Templating pattern

chezmoi treats files as templates when they have .tmpl suffix (or live under .chezmoitemplates), and exposes machine facts like .chezmoi.os and .chezmoi.hostname.

That lets you do things like:

Different filesystem roots on macOS vs Linux
Company-only servers on work laptops
Personal-only servers on home machines

Example gate in template:

{{- if eq .chezmoi.hostname "work-laptop" -}}
# render internal MCP server
{{- end -}}

Symlinks and private data

chezmoi source-state attributes are important for this problem:

symlink_ to create symlink targets
private_ for sensitive files/permissions
encrypted_ + age/gpg encryption for secret-bearing material

This is ideal for MCP because tokens and headers frequently differ by machine/account.

Recommended split:

Keep server topology in a committed template/data file
Keep secrets in encrypted/private files or external secret providers
Render env var references into final tool configs

Mapping rules (the critical part)

Define clear transformation rules once:

transport: stdio
- Codex: TOML command/args/env under [mcp_servers.<name>]
- Claude/Cursor/VSCode/Copilot: JSON object with command args env and tool-specific type field if required
transport: http (or sse)
- Codex: url (+ auth/header fields)
- JSON tools: url, headers, and possibly type (http/sse)
Optional per-tool fields
- Keep them in an overrides map in canonical YAML if absolutely necessary
- Avoid polluting the base model with vendor-only keys unless needed

Suggested generation flow

Edit canonical servers.yaml
Run chezmoi apply
Let templates produce:
- ~/.codex/config.toml MCP block
- ~/.claude.json or project .mcp.json projection
- ~/.cursor/mcp.json
- .vscode/mcp.json
- ~/.copilot/mcp-config.json (if used in your setup)

If you want strict reproducibility, generate all from templates only and never edit generated targets directly.

Real-world caveats

Copilot and Cursor MCP features are evolving quickly; treat adapters as projection layers, not permanent schemas.
Claude has multiple config surfaces (settings.json, ~/.claude.json, .mcp.json), so be explicit about which one your team standardizes on.
Project-level files (.vscode/mcp.json, .mcp.json, .codex/config.toml) are great for shared defaults; user-level files should hold personal secrets and machine specifics.

Bottom line

The durable strategy is not "pick one tool format."

It is:

One canonical MCP model
Many generated vendor configs
chezmoi templates + machine facts + private/encrypted files to keep it safe and portable

That gives you consistency across Codex, Claude, Cursor, and Copilot without locking yourself to one vendor schema.

Sources

One Skills Brain for Codex, Claude, Cursor, and Copilot with Chezmoi

Lukas Wolfsteiner — Sat, 07 Mar 2026 21:10:09 +0000

One Skills Brain for Codex, Claude, Cursor, and Copilot with Chezmoi

When you use multiple coding agents across multiple machines, the same prompt often behaves differently for a simple reason: your agent skills and MCP wiring drift over time.

Typical failure modes:

a skill is updated in one tool but not the others
MCP servers are configured differently per machine
one tool reads user-level config, another reads project-level config, and behavior diverges

The initial problem is not just dotfiles sync. It is maintaining one consistent agent behavior contract across Codex, Claude, Cursor, and Copilot despite different config formats and file locations.

The solution in this guide is to separate concerns:

one canonical skills directory: ~/.agent-skills/skills
one canonical MCP intent (shared definitions rendered per tool)
one dotfiles manager (chezmoi) to materialize tool-native adapters

Why this works:

skills stay identical because they live in one place
each tool keeps its native schema, so updates are compatible with official behavior
chezmoi templates and symlinks remove manual copy/paste and reduce drift
path differences are explicit and auditable

All path references below follow:

agent-storage-map.md

Path contract (from agent-storage-map)

Codex
User config: ~/.codex/config.toml
Project config: .codex/config.toml
Skills: .agents/skills and SKILL.md folders
Claude Code
Main MCP config: ~/.claude.json
Dedicated MCP file: ~/.claude/mcp_servers.json (lower precedence than ~/.claude.json)
Settings: ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json
Sub-agents: ~/.claude/agents/, .claude/agents/
Cursor
MCP config: ~/.cursor/mcp.json, .cursor/mcp.json
Skills: ~/.cursor/skills/, .cursor/skills/
Compatibility skills paths include ~/.codex/skills/, ~/.claude/skills/
GitHub Copilot
MCP config: ~/.copilot/mcp-config.json
Skills: ~/.copilot/skills/, .copilot/skills/

Why symlinks (not hard links)

Use symlinks for shared skills directories.

explicit target path (readlink)
works natively with chezmoi symlink_ files
easier operationally than hard links for directory trees

Chezmoi source tree (concrete)

This is the chezmoi source-state tree ($(chezmoi source-path)):

~/.local/share/chezmoi/
├── dot_agent-skills/
│   ├── README.md
│   ├── skills/
│   │   ├── commit-style/
│   │   │   └── SKILL.md
│   │   └── test-triage/
│   │       └── SKILL.md
│   └── mcp/
│       ├── codex-mcp.toml.tmpl
│       ├── generic-mcp.json.tmpl
│       └── copilot-mcp.json.tmpl
├── dot_codex/
│   ├── config.toml.tmpl
│   └── symlink_skills.tmpl
├── private_dot_claude.json.tmpl
├── dot_claude/
│   └── settings.json.tmpl
├── dot_cursor/
│   ├── mcp.json.tmpl
│   └── symlink_skills.tmpl
└── dot_copilot/
    ├── mcp-config.json.tmpl
    └── symlink_skills.tmpl

Chezmoi attribute reminders:

dot_ -> leading dot in target
private_ -> stricter permissions in target
symlink_ -> create a symlink target
.tmpl -> template rendering

Command set

First machine

chezmoi init git@github.com:<you>/<dotfiles>.git
cd "$(chezmoi source-path)"

# Optional: import existing files
chezmoi add ~/.codex/config.toml
chezmoi add ~/.claude.json
chezmoi add ~/.claude/settings.json
chezmoi add ~/.cursor/mcp.json
chezmoi add ~/.copilot/mcp-config.json

chezmoi diff
chezmoi apply -v

git add .
git commit -m "feat: unify skills and mcp adapters"
git push

Additional machines

chezmoi init git@github.com:<you>/<dotfiles>.git
chezmoi update -v

Daily flow

chezmoi edit ~/.codex/config.toml
chezmoi diff
chezmoi apply -v

Shared skills content

Create all skills once in dot_agent-skills/skills.

Example dot_agent-skills/skills/commit-style/SKILL.md:

# commit-style

## Goal
Create clear conventional commits.

## Rules
- Keep subject under 50 chars.
- Use imperative present tense.
- Explain user impact in body.

After apply, this becomes ~/.agent-skills/skills/... and is your canonical skill bank.

Shared MCP templates

Keep one MCP intent and render per tool schema.

`dot_agent-skills/mcp/codex-mcp.toml.tmpl`

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "{{ .homeDir }}/.agent-skills/skills"]

[mcp_servers.git]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-git", "--repository", "{{ .homeDir }}/Developer"]

`dot_agent-skills/mcp/generic-mcp.json.tmpl` (Claude/Cursor style)

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "{{ .homeDir }}/.agent-skills/skills"]
    },
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git", "--repository", "{{ .homeDir }}/Developer"]
    }
  }
}

`dot_agent-skills/mcp/copilot-mcp.json.tmpl`

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "{{ .homeDir }}/.agent-skills/skills"]
    },
    "git": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git", "--repository", "{{ .homeDir }}/Developer"]
    }
  }
}

Per-tool templates

1) Codex

dot_codex/config.toml.tmpl

model = "gpt-5-codex"
approval_policy = "on-request"

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "{{ .homeDir }}/.agent-skills/skills"]

[mcp_servers.git]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-git", "--repository", "{{ .homeDir }}/Developer"]

dot_codex/symlink_skills.tmpl

{{ .homeDir }}/.agent-skills/skills

Result: ~/.codex/skills -> ~/.agent-skills/skills
Use this mainly as a compatibility anchor for tools that read Codex-style skills paths.
For Codex itself, keep project skills in .agents/skills when you want repository-local behavior.

2) Claude Code

private_dot_claude.json.tmpl

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "{{ .homeDir }}/.agent-skills/skills"]
    },
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git", "--repository", "{{ .homeDir }}/Developer"]
    }
  }
}

dot_claude/settings.json.tmpl

{
  "permissions": {
    "allow": [],
    "deny": []
  }
}

For project-level MCP, use .mcp.json with the same filesystem path.
For agent logic, prefer documented .claude/agents/ over .claude/skills/.

3) Cursor

dot_cursor/mcp.json.tmpl

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "{{ .homeDir }}/.agent-skills/skills"]
    },
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git", "--repository", "{{ .homeDir }}/Developer"]
    }
  }
}

dot_cursor/symlink_skills.tmpl

{{ .homeDir }}/.agent-skills/skills

Result: ~/.cursor/skills -> ~/.agent-skills/skills

4) GitHub Copilot

dot_copilot/mcp-config.json.tmpl

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "{{ .homeDir }}/.agent-skills/skills"]
    },
    "git": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git", "--repository", "{{ .homeDir }}/Developer"]
    }
  }
}

dot_copilot/symlink_skills.tmpl

{{ .homeDir }}/.agent-skills/skills

Result: ~/.copilot/skills -> ~/.agent-skills/skills

Validation

readlink ~/.codex/skills
readlink ~/.cursor/skills
readlink ~/.copilot/skills
ls ~/.agent-skills/skills

chezmoi status
chezmoi diff
chezmoi verify

Expected: all symlinks resolve to ~/.agent-skills/skills, and each MCP file targets that same path.

Feature parity with `skills-sync`

I reviewed skills-sync feature usage and mapped it to chezmoi primitives.

Single source workspace
Chezmoi equivalent: one source state with canonical dot_agent-skills/skills.
Symlink distribution
Chezmoi equivalent: symlink_*.tmpl entries per tool.
Profile switching (use <profile>)
Chezmoi equivalent: .chezmoidata/profiles.yaml + template conditionals.
Runtime materialization (sync)
Chezmoi equivalent: chezmoi apply -v.
Seed content (init --seed)
Chezmoi equivalent: commit baseline skills/templates in source state.
Upstream ingestion (add-upstream, add-skill)
Chezmoi equivalent: external_ or scripted run_onchange_ sync jobs.
Drift/inventory (agents drift, agents inventory)
Chezmoi equivalent: chezmoi status/diff/verify plus symlink checks.

Profile-aware template example

Create .chezmoidata/profiles.yaml:

active_profile: personal
profiles:
  personal:
    dev_root: "~/Developer"
  work:
    dev_root: "~/Work"

Use in template:

{{- $p := index .profiles .active_profile -}}
[mcp_servers.git]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-git", "--repository", "{{ $p.dev_root }}"]

Switch profile by changing active_profile, then:

chezmoi apply -v

Upstream sync example

run_onchange_after_50-sync-upstream-skills.sh.tmpl

#!/usr/bin/env bash
set -eu

ROOT="$HOME/.agent-skills/skills/upstream"
mkdir -p "$ROOT"

sync_repo() {
  name="$1"
  url="$2"
  dir="$ROOT/$name"
  if [ -d "$dir/.git" ]; then
    git -C "$dir" pull --ff-only
  else
    git clone "$url" "$dir"
  fi
}

sync_repo "matlab_skills" "https://github.com/matlab-deep-learning/llm-agents-with-mcp.git"

Apply with:

chezmoi apply -v

Security and portability notes

Keep tokens in env vars, not committed config files.
Use private_ for files that may carry sensitive values.
Use {{ .homeDir }} in templates for cross-machine portability.

This pattern gives one skill bank, one MCP intent, four adapters, and minimal drift.

Cheers,
Lukas

Forem: Lukas Wolfsteiner

One MCP Configuration for Codex, Claude, Cursor, and Copilot with chezmoi

Why this works

What each tool expects today

Codex

Claude Code

Cursor

GitHub Copilot / VS Code

Common ground: a normalized MCP model

chezmoi layout that scales

Templating pattern

Symlinks and private data

Mapping rules (the critical part)

Suggested generation flow

Real-world caveats

Bottom line

Sources

One Skills Brain for Codex, Claude, Cursor, and Copilot with Chezmoi

One Skills Brain for Codex, Claude, Cursor, and Copilot with Chezmoi

Path contract (from agent-storage-map)

Why symlinks (not hard links)

Chezmoi source tree (concrete)

Command set

First machine

Additional machines

Daily flow

Shared skills content

Shared MCP templates

dot_agent-skills/mcp/codex-mcp.toml.tmpl

dot_agent-skills/mcp/generic-mcp.json.tmpl (Claude/Cursor style)

dot_agent-skills/mcp/copilot-mcp.json.tmpl

Per-tool templates

1) Codex

2) Claude Code

3) Cursor

4) GitHub Copilot

Validation

Feature parity with skills-sync

Profile-aware template example

Upstream sync example

Security and portability notes

`dot_agent-skills/mcp/codex-mcp.toml.tmpl`

`dot_agent-skills/mcp/generic-mcp.json.tmpl` (Claude/Cursor style)

`dot_agent-skills/mcp/copilot-mcp.json.tmpl`

Feature parity with `skills-sync`