CCA · Foundations

ตั้งค่า MCP server: .mcp.json, ~/.claude.json, และ env var

แนวคิด

Claude Code เชื่อมต่อ MCP server ได้หลายตัว และมี scope ให้เลือกว่าจะเก็บ config ไว้ที่ไหน exam guide เน้นสองแบบหลัก คือ project-level ในไฟล์ .mcp.json สำหรับ tooling ที่แชร์ทั้งทีม กับ user-level ในไฟล์ ~/.claude.json สำหรับ server ส่วนตัวหรือทดลอง

เอกสารจริงละเอียดกว่านั้นเล็กน้อย มีสาม scope ค่าเริ่มต้นคือ local scope เก็บใน ~/.claude.json ผูกกับ project ปัจจุบันและเป็นของเราคนเดียว เหมาะกับ server ทดลองหรือที่มี credential ที่ไม่อยากขึ้น version control ถัดมาคือ project scope เก็บใน .mcp.json ที่ราก project ออกแบบมาให้ commit เข้า version control เพื่อให้ทุกคนในทีมได้ tool ชุดเดียวกัน และ user scope เก็บใน ~/.claude.json ให้ใช้ได้ข้ามทุก project บนเครื่อง สังเกตว่าทั้ง local และ user เก็บในไฟล์ ~/.claude.json เดียวกัน ส่วน .mcp.json คือไฟล์ของทีมที่ commit ได้ เมื่อชื่อชนกัน ลำดับความสำคัญคือ local ก่อน project แล้วจึง user

ทำไมสำคัญ

การแยก scope ช่วยจัดการ credential โดยไม่ commit ความลับ เพราะ .mcp.json ที่แชร์ทั้งทีมไม่ควรมี token ตรง ๆ Claude Code จึงรองรับ environment variable expansion ใน .mcp.json มีสองรูปแบบ คือ ${VAR} ที่แทนด้วยค่าของ environment variable และ ${VAR:-default} ที่ใช้ค่า default เมื่อ VAR ไม่ถูกตั้ง การ expand ทำได้ในหลายที่ ได้แก่ command, args, env, url, และ headers ทำให้เราเขียน ${GITHUB_TOKEN} ในไฟล์ที่ commit ได้ โดยค่าจริงมาจาก environment ของแต่ละเครื่อง ถ้า variable ที่จำเป็นไม่ถูกตั้งและไม่มี default Claude Code จะ parse config ไม่ผ่าน

เมื่อ server หลายตัวถูกตั้งค่าไว้ tool จากทุก server จะถูกค้นพบตอนเชื่อมต่อ ผ่านคำขอ tools/list และพร้อมใช้งานพร้อมกันกับ agent แปลว่า agent เห็น tool ของทุก server ในคราวเดียว

จุดที่ exam guide เน้นเป็นทักษะคือการเสริมคำอธิบายของ MCP tool ให้ละเอียด อธิบายความสามารถและผลลัพธ์ให้ชัด เพื่อกันไม่ให้ agent เลือกใช้ built-in tool เช่น Grep แทน MCP tool ที่ทำงานได้ดีกว่า นี่คือหลักเดียวกับบทเรื่อง description คือ description ที่ดีคือกลไกที่ทำให้ tool ถูกเลือก

ตัวอย่าง

// .mcp.json ที่ราก project (commit ได้) — ใช้ env var expansion
{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "${GITHUB_MCP_URL:-https://api.githubcopilot.com/mcp/}",
      "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
    }
  }
}

${GITHUB_TOKEN} ไม่ถูก commit เป็นค่าจริง ต่างเครื่องต่างเติมค่าเอง ส่วน server ทดลองส่วนตัวเก็บใน ~/.claude.json (local หรือ user scope) แทน

เช็คความเข้าใจ

ไฟล์ .mcp.json กับ ~/.claude.json เก็บ MCP server scope ใดบ้าง

env var expansion ใน .mcp.json ทำงานอย่างไร และถ้า variable จำเป็นไม่ถูกตั้งจะเกิดอะไร

อ่านต่อ