diff --git a/packages/mcp/README.md b/packages/mcp/README.md
index bc2de53..6c2c7da 100644
--- a/packages/mcp/README.md
+++ b/packages/mcp/README.md
@@ -60,14 +60,15 @@ Edit `~/Library/Application\ Support/Claude/claude_desktop_config.json`:
 }
 ```
 
-### VS Code / Codex
+### VS Code
 
-Published package:
+Add the published package to `.vscode/mcp.json`:
 
 ```json
 {
-  "mcpServers": {
+  "servers": {
     "microlink": {
+      "type": "stdio",
       "command": "npx",
       "args": ["-y", "@microlink/mcp"],
       "env": {
@@ -78,18 +79,15 @@ Published package:
 }
 ```
 
-Local repository:
+For a local repository checkout, replace the server command with:
 
 ```json
 {
-  "mcpServers": {
-    "microlink": {
-      "command": "node",
-      "args": ["/absolute/path/to/mcp/src/index.js"],
-      "env": {
-        "MICROLINK_API_KEY": "YOUR_MICROLINK_API_KEY"
-      }
-    }
+  "type": "stdio",
+  "command": "node",
+  "args": ["/absolute/path/to/mcp/src/index.js"],
+  "env": {
+    "MICROLINK_API_KEY": "YOUR_MICROLINK_API_KEY"
   }
 }
 ```
diff --git a/packages/mcp/test/readme-client-config.test.js b/packages/mcp/test/readme-client-config.test.js
new file mode 100644
index 0000000..46751e8
--- /dev/null
+++ b/packages/mcp/test/readme-client-config.test.js
@@ -0,0 +1,36 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { readFile } from 'node:fs/promises'
+
+const readme = await readFile(new URL('../README.md', import.meta.url), 'utf8')
+
+function section (start, end) {
+  return readme.slice(readme.indexOf(start), readme.indexOf(end))
+}
+
+test('VS Code examples use its native MCP configuration shape', () => {
+  const vscode = section('### VS Code\n', '### Cursor\n')
+  const published = section(
+    'Add the published package to `.vscode/mcp.json`:',
+    'For a local repository checkout'
+  )
+  const local = section('For a local repository checkout', '### Cursor\n')
+
+  assert.match(vscode, /\.vscode\/mcp\.json/)
+  assert.doesNotMatch(vscode, /"mcpServers":/)
+
+  assert.match(published, /"servers":/)
+  assert.match(published, /"type": "stdio"/)
+  assert.match(published, /"command": "npx"/)
+  assert.match(published, /"MICROLINK_API_KEY"/)
+
+  assert.match(local, /"type": "stdio"/)
+  assert.match(local, /"command": "node"/)
+  assert.match(local, /"args": \["\/absolute\/path\/to\/mcp\/src\/index\.js"\]/)
+  assert.match(local, /"MICROLINK_API_KEY"/)
+})
+
+test('Cursor example keeps the portable mcpServers shape', () => {
+  const cursor = section('### Cursor\n', '## Usage\n')
+  assert.match(cursor, /"mcpServers":/)
+})