---

name: mcp-registration description: Register and validate MCP server settings in project-local or user-global configs. Use when asked to add/update MCP entries (mcp.json, .claude/mcp.json, or user config), when tools do not appear in the client, or when a task requires end-to-end MCP smoke testing (listTools and callTool). Trigger on requests like "MCP登録", "mcp.json設定", "MCPサーバ追加", and "MCP動作検証".

MCP Registration

Overview

Use this skill to add MCP server registrations safely and verify they actually work. Always finish with executable verification, not config edits alone.

Workflow

1. Identify the target config file first

Check these in order and use the one the user requested:

• Project-local: mcp.json
• Project-local: .claude/mcp.json
• User-global (Codex desktop): ~/Library/Application Support/Code/User/mcp.json

Preserve the existing top-level schema:

• If file uses mcpServers, add under mcpServers.
• If file uses servers, add under servers.
• If file does not exist, prefer mcpServers for project-local files unless the user specifies another format.

2. Register the server with minimum required fields

Use this shape:

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["tsx", "mcp/server.ts"],
      "cwd": "/absolute/path/to/project",
      "env": {
        "KEY": "<token>"
      }
    }
  }
}

Rules:

• Keep cwd absolute.
• Keep secrets out of committed project files unless user explicitly requests otherwise.
• Use placeholders like <token> in repo-managed configs.
• Do not silently change key names (mcpServers vs servers).

3. Validate JSON and startup behavior

Run:

• JSON syntax check (open/parse file).
• Type/build check for server project if applicable.
• Startup check with expected behavior:
  • If env missing, confirm clear error message and non-zero exit.
  • If env provided, confirm startup log like ...Server running on stdio.

4. Execute end-to-end smoke test

Prefer MCP SDK client verification over manual assumptions:

1. Spawn server with StdioClientTransport.
2. Call listTools and verify expected tool names.
3. Call core tools in a realistic sequence.
4. Assert returned payloads include success: true.
5. Close client cleanly.

For DB-backed servers without production credentials, use local test env when possible (e.g., file: SQLite/libSQL URL).

5. Finish with actionable report

Report:

• Which config file was updated.
• Exact server key added.
• Verification commands executed.
• Tool-level smoke test result.
• Remaining manual action (for example replacing <token>).

⚠️ よくある落とし穴

• ホームディレクトリ全検索でのパーミッションエラー: mcp.json を探すために ~/ を再帰検索するとmacOSの権限エラーが大量に出る。プロジェクトルート、.claude/、VSCode設定ディレクトリなどターゲットパスを先に確認する
• プロセス終了コードの未確認: 起動確認で標準出力だけ見てexit codeをチェックしないと、致命的なブートエラーを見逃す
• config登録だけで検証を省略: mcp.json に追加しただけで完了とすると、スキーマ不一致やランタイムエラーが本番で初めて発覚する。必ず tools/list + tools/call まで通す
• APIキー/トークンのコミット事故: プロジェクト管理のconfigファイルに実際のシークレットを書いてコミットするとセキュリティインシデントになる。<token> プレースホルダか source .env.local 方式を使う

References

• references/mcp-registration-checklist.md: execution checklist and decision rules.
• references/competitor-ui-viewer-notes-2026-02.md: practical tips captured from a real implementation.