Skip to content

MCP CLI Management

Manage MCP (Model Context Protocol) servers from the command line.

Overview

Claude Code provides CLI commands to add, remove, and manage MCP servers. Nova AI uses SDK-based MCP servers (in-process) for 69x faster tool execution compared to traditional stdio servers.

Quick Reference

Command Description
claude mcp list List all configured servers
claude mcp add <name> Add a new server
claude mcp remove <name> Remove a server
claude mcp get <name> Show server details

Commands

List Servers

# List all configured MCP servers
claude mcp list

# Verbose output with connection status
claude mcp list --verbose

Example Output: 

MCP Servers (6 configured):
  kb        src/orchestrator/tools/sdk_mcp_kb_server.py      [SDK]
  github    src/orchestrator/tools/sdk_mcp_github_server.py  [SDK]
  memory    src/orchestrator/tools/sdk_mcp_memory_server.py  [SDK]
  blarify   src/orchestrator/tools/sdk_mcp_blarify_server.py [SDK]
  composio  (external)                                        [SDK]
  context7  (external)                                        [SDK]

Add Server

# Add a project-scoped server (stored in .claude/settings.json)
claude mcp add my-server --command "python src/tools/my_server.py"

# Add a user-scoped server (available in all projects)
claude mcp add my-server --command "python path/to/server.py" --scope user

# Add with environment variables
claude mcp add github --command "python sdk_mcp_github_server.py" \
  --env GITHUB_TOKEN='$GITHUB_TOKEN'

# Add with arguments
claude mcp add kb --command "python sdk_mcp_kb_server.py" \
  --args "--kb-path .nova/kb --top-k 10"

Scopes: - project (default) - Stored in .claude/settings.json (committed) - user - Stored in ~/.claude/settings.json (personal, not committed)

Remove Server

# Remove a server
claude mcp remove my-server

# Remove from user scope
claude mcp remove my-server --scope user

Get Server Details

# Show server configuration
claude mcp get kb

# Output:
# Server: kb
# Command: python src/orchestrator/tools/sdk_mcp_kb_server.py
# Scope: project
# Environment:
#   KB_PATH: .nova/kb

Nova AI's 6 Core Servers

Server Purpose Location
kb FAISS knowledge base (5.4GB semantic search) src/orchestrator/tools/sdk_mcp_kb_server.py
github PR/issue operations src/orchestrator/tools/sdk_mcp_github_server.py
memory Persistent storage across sessions src/orchestrator/tools/sdk_mcp_memory_server.py
blarify Code analysis, circular dependency detection src/orchestrator/tools/sdk_mcp_blarify_server.py
composio 100+ app integrations (Slack, Jira, etc.) External (Composio SDK)
context7 Live library documentation External (Context7 API)

Configuration File Format

MCP servers are configured in .claude/settings.json:

{
  "mcpServers": {
    "kb": {
      "command": "python",
      "args": ["src/orchestrator/tools/sdk_mcp_kb_server.py"],
      "env": {
        "KB_PATH": ".nova/kb"
      }
    },
    "github": {
      "command": "python",
      "args": ["src/orchestrator/tools/sdk_mcp_github_server.py"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "custom-server": {
      "command": "node",
      "args": ["path/to/server.js", "--port", "3000"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      }
    }
  }
}

Fields: - command - Executable to run (python, node, etc.) - args - Array of command-line arguments - env - Environment variables (supports ${VAR} syntax for secrets)

Creating Custom MCP Servers

1. Create Server File

# src/tools/my_custom_server.py
from mcp.server import Server
from mcp.types import Tool

server = Server("my-custom-server")

@server.tool()
async def my_tool(query: str) -> str:
    """My custom tool description."""
    # Implementation
    return f"Result for: {query}"

if __name__ == "__main__":
    server.run()

2. Register with Claude Code

claude mcp add my-server --command "python src/tools/my_custom_server.py"

3. Verify Registration

claude mcp list
claude mcp get my-server

4. Use in Agents

Tools become available as mcp__my-server__my_tool:

# In agent code
result = await mcp__my_server__my_tool(query="test")

Troubleshooting

Server Not Found

# Check if server is registered
claude mcp list

# Verify path exists
ls -la src/orchestrator/tools/sdk_mcp_kb_server.py

Connection Timeout

# Test server directly
python src/orchestrator/tools/sdk_mcp_kb_server.py --test

# Check for port conflicts
lsof -i :3000

Authentication Errors

# Verify environment variables
echo $GITHUB_TOKEN
echo $ANTHROPIC_API_KEY

# Check .env file exists
cat .env | grep -v "^#" | grep -v "^$"

Permission Denied

# Check file permissions
chmod +x src/orchestrator/tools/sdk_mcp_kb_server.py

# Verify Python path
which python
python --version

Debug Mode

# Enable verbose logging
CLAUDE_DEBUG=1 claude mcp list --verbose

# Test specific server
claude mcp test kb

SDK vs stdio Servers

Nova AI uses SDK-based servers (in-process) instead of stdio:

Feature stdio (Traditional) SDK (Nova AI)
Latency ~100ms per call ~1.5ms per call
Speedup 1x 69x faster
Process Subprocess In-process
Communication JSON-RPC over pipes Direct function calls
Overhead High (spawn, serialize) Minimal

Why SDK? - No subprocess spawning overhead - No JSON serialization/deserialization - Direct memory access - Better error handling

Best Practices

1. Use Project Scope for Team Servers

# Team servers go in .claude/settings.json (committed)
claude mcp add kb --command "python ..." --scope project

2. Use User Scope for Personal Servers

# Personal servers go in ~/.claude/settings.json (not committed)
claude mcp add my-dev-tool --command "..." --scope user

3. Use Environment Variables for Secrets

{
  "mcpServers": {
    "github": {
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Never hardcode secrets in settings.json.

4. Test Servers Before Committing

# Test locally first
python src/tools/my_server.py --test

# Then add to config
claude mcp add my-server --command "..."

# Verify
claude mcp list