diff --git a/docs/mcp-config.md b/docs/mcp-config.md
index c0fed4efa..3f4c631ad 100644
--- a/docs/mcp-config.md
+++ b/docs/mcp-config.md
@@ -15,14 +15,14 @@ Source of truth in code:
 OMP can discover MCP servers from multiple tools (`.claude/`, `.cursor/`, `.vscode/`, `opencode.json`, and more), but for OMP-native configuration you should usually use one of these files:
 
 - Project: `.omp/mcp.json`
-- User: `~/.omp/mcp.json`
+- User: `~/.omp/agent/mcp.json`
 
 OMP also accepts fallback standalone files in the project root:
 
 - `mcp.json`
 - `.mcp.json`
 
-Use `.omp/mcp.json` when you want OMP to own the configuration. Use root `mcp.json` / `.mcp.json` only when you want a portable fallback file that other MCP clients may also read.
+Use `.omp/mcp.json` or `~/.omp/agent/mcp.json` when you want OMP to own the configuration. Use root `mcp.json` / `.mcp.json` only when you want a portable fallback file that other MCP clients may also read.
 
 ## Add a schema reference
 
@@ -315,7 +315,7 @@ This matches GitHub's official local Docker image `ghcr.io/github/github-mcp-ser
 
 This is the part that usually trips people up.
 
-### In `.omp/mcp.json` and `~/.omp/mcp.json`
+### In `.omp/mcp.json` and `~/.omp/agent/mcp.json`
 
 Before OMP launches a server or makes an HTTP request, it resolves `env` and `headers` values like this:
 
@@ -362,11 +362,11 @@ Example:
 }
 ```
 
-If you want the least surprising OMP behavior, prefer `.omp/mcp.json` and use explicit env/header values.
+If you want the least surprising OMP behavior, prefer `.omp/mcp.json` or `~/.omp/agent/mcp.json` and use explicit env/header values.
 
 ## `disabledServers`
 
-`disabledServers` is mainly useful in the user config file (`~/.omp/mcp.json`) when a server is discovered from some other source and you want OMP to ignore it without editing that other tool's config.
+`disabledServers` is mainly useful in the user config file (`~/.omp/agent/mcp.json`) when a server is discovered from some other source and you want OMP to ignore it without editing that other tool's config.
 
 Example:
 
@@ -414,7 +414,7 @@ OMP does not merge duplicate server definitions across files. Discovery provider
 
 In practice:
 
-- prefer `.omp/mcp.json` or `~/.omp/mcp.json` when you want an OMP-specific override
+- prefer `.omp/mcp.json` or `~/.omp/agent/mcp.json` when you want an OMP-specific override
 - keep server names unique across tools when possible
 - use `disabledServers` in the user config when a third-party config keeps reintroducing a server you do not want
 
diff --git a/docs/mcp-server-tool-authoring.md b/docs/mcp-server-tool-authoring.md
index 3f8333a52..befe9d6de 100644
--- a/docs/mcp-server-tool-authoring.md
+++ b/docs/mcp-server-tool-authoring.md
@@ -62,7 +62,7 @@ The dedicated fallback provider in `src/discovery/mcp-json.ts` reads project-roo
 
 In practice MCP servers also come from higher-priority providers (for example native `.omp/...` and tool-specific config dirs). Authoring guidance:
 
-- Prefer `.omp/mcp.json` (project) or `~/.omp/mcp.json` (user) for explicit control.
+- Prefer `.omp/mcp.json` (project) or `~/.omp/agent/mcp.json` (user) for explicit control.
 - Use root `mcp.json` / `.mcp.json` when you need fallback compatibility.
 - Reusing the same server name in multiple sources causes precedence shadowing, not merge.
 
diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 4ca04f07e..d4fab9711 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- Fixed MCP config docs and schema to use `~/.omp/agent/mcp.json` for user-scoped OMP-native MCP config while keeping project config at `<cwd>/.omp/mcp.json`
+
 ## [14.0.4] - 2026-04-10
 ### Added
 
diff --git a/packages/coding-agent/src/config/mcp-schema.json b/packages/coding-agent/src/config/mcp-schema.json
index 4708a9c25..7ffb73458 100644
--- a/packages/coding-agent/src/config/mcp-schema.json
+++ b/packages/coding-agent/src/config/mcp-schema.json
@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
   "title": "OMP MCP configuration",
-  "description": "Schema for mcp.json, .mcp.json, .omp/mcp.json, and ~/.omp/mcp.json used by the OMP coding agent.",
+  "description": "Schema for mcp.json, .mcp.json, .omp/mcp.json, and ~/.omp/agent/mcp.json used by the OMP coding agent.",
   "type": "object",
   "additionalProperties": false,
   "properties": {