SOP: Adding Custom MCP Servers to Conductor (Claude Code)

Overview

This guide provides step-by-step instructions for adding custom MCP (Model Context Protocol) servers to Conductor when the UI doesn't provide a built-in option.

Prerequisites

• Conductor (Claude Code) installed
• Terminal access
• jq command-line JSON processor installed
• MCP server package details (npm package name or command)

Problem

The Conductor UI only provides quick-add options for a few MCPs (Linear, Figma, Context7, Sentry). Custom MCPs need to be added manually to the configuration file.

Solution

Step 1: Backup Your Configuration

cp ~/.claude.json ~/.claude.json.backup

Why: Always create a backup before modifying configuration files to prevent data loss.

---

Step 2: Verify Current MCP Configuration

jq '.mcpServers' ~/.claude.json

Expected output: You should see existing MCPs like context7:

{
  "context7": {
    "args": ["-y", "@upstash/context7-mcp@latest"],
    "command": "npx",
    "env": {},
    "type": "stdio"
  }
}

---

Step 3: Add the New MCP Server

Replace <mcp-name> and <package-name> with your specific MCP details:

jq '.mcpServers += {"<mcp-name>": {"type": "stdio", "command": "npx", "args": ["-y", "<package-name>"], "env": {}}}' ~/.claude.json > ~/.claude.json.tmp && mv ~/.claude.json.tmp ~/.claude.json

Example for Shopify MCP:

jq '.mcpServers += {"shopify-dev-mcp": {"type": "stdio", "command": "npx", "args": ["-y", "@shopify/dev-mcp@latest"], "env": {}}}' ~/.claude.json > ~/.claude.json.tmp && mv ~/.claude.json.tmp ~/.claude.json

---

Step 4: Verify the Configuration

jq '.mcpServers' ~/.claude.json

Expected output: You should see both the original and new MCP:

{
  "context7": {
    "args": ["-y", "@upstash/context7-mcp@latest"],
    "command": "npx",
    "env": {},
    "type": "stdio"
  },
  "shopify-dev-mcp": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@shopify/dev-mcp@latest"],
    "env": {}
  }
}

---

Step 5: Restart Conductor

1. Quit Conductor completely (Cmd + Q on macOS)
2. Relaunch Conductor

Why: Configuration changes only take effect after a full restart.

---

Step 6: Verify MCP is Active

Run this command to check MCP status:

claude mcp list

Expected output:

Checking MCP server health...

context7: npx -y @upstash/context7-mcp@latest - ✓ Connected
shopify-dev-mcp: npx -y @shopify/dev-mcp@latest - ✓ Connected

---

Common MCP Server Examples

Shopify Development MCP

jq '.mcpServers += {"shopify-dev-mcp": {"type": "stdio", "command": "npx", "args": ["-y", "@shopify/dev-mcp@latest"], "env": {}}}' ~/.claude.json > ~/.claude.json.tmp && mv ~/.claude.json.tmp ~/.claude.json

Custom Local MCP

For locally installed MCP servers:

jq '.mcpServers += {"my-custom-mcp": {"type": "stdio", "command": "/path/to/mcp/server", "args": [], "env": {}}}' ~/.claude.json > ~/.claude.json.tmp && mv ~/.claude.json.tmp ~/.claude.json

---

Troubleshooting

Issue: MCP shows as disconnected

Solution:

1. Verify the package name is correct
2. Check that npx can install the package: npx -y <package-name>
3. Review Conductor logs for error messages

Issue: JSON syntax error after editing

Solution:

1. Restore from backup: cp ~/.claude.json.backup ~/.claude.json
2. Verify JSON is valid: jq '.' ~/.claude.json
3. Re-run the command carefully

Issue: Changes don't appear after restart

Solution:

1. Verify the MCP was added: jq '.mcpServers' ~/.claude.json
2. Ensure you did a full quit and restart of Conductor
3. Check for multiple Conductor processes: ps aux | grep Conductor

---

Configuration File Location

• macOS/Linux: ~/.claude.json
• Global MCP Key: .mcpServers (affects all Conductor instances)
• Project-level: .localProjects["/path/to/project"].mcpServers (project-specific)

---

Notes

• MCP settings apply globally to all instances of Claude Code
• Project-level MCP configuration is not yet supported via UI
• Always backup before modifying configuration files
• The CLI command claude mcp add may not always work correctly for all MCPs
• Manual JSON editing is the most reliable method currently

---

References

• Conductor MCP Documentation
• Model Context Protocol (MCP)
• Available MCP Servers

---

Last Updated: 2025-10-22 Tested On: Conductor (Claude Code) on macOS