FoundryVTT/MCP_SERVERS_GUIDE.md

MCP Servers - Complete Guide

Comprehensive documentation for all Model Context Protocol (MCP) servers used in Claude Code Version: 1.0.0 | Last Updated: 2025-10-20

---

Table of Contents

1. Overview
2. Quick Start
3. Installation & Setup
4. Available MCP Servers
5. Usage Guide
6. Configuration
7. Best Practices
8. Troubleshooting
9. Advanced Topics

---

Overview

What Are MCP Servers?

Model Context Protocol (MCP) servers extend Claude Code's capabilities by providing:

• External integrations (databases, browsers, desktop automation)
• Enhanced code navigation and analysis
• Persistent and temporary memory systems
• Real-time documentation access
• Complex reasoning capabilities

MCP Servers in This Project

This project includes 8 fully configured MCP servers:

#	Server	Type	Purpose
1	Serena	Python (uvx)	Code navigation + persistent memory
2	Sequential Thinking	Node.js (npx)	Complex reasoning engine
3	Database Server	Node.js (npx)	SQL Server integration
4	Context7	Node.js (npx)	Library documentation
5	Memory	Node.js (npx)	Knowledge graph (session)
6	Fetch	Python (uvx)	Web content retrieval
7	Windows MCP	Python (uv)	Desktop automation
8	Playwright	Node.js (npx)	Browser automation

MCP vs Core Tools

Core Tools (built-in):

• Read, Write, Edit - File operations
• Glob, Grep - File search
• Bash - Shell commands
• WebSearch, WebFetch - Web access

MCP Servers (extended):

• Semantic code navigation
• Persistent knowledge storage
• Complex reasoning
• Browser/desktop automation
• Database access

---

Quick Start

One-Command Setup

Windows (PowerShell):

.\.claude\tools\setup-all-mcp-servers.ps1

Linux/Mac (Bash):

./.claude/tools/setup-all-mcp-servers.sh

Verify Installation

# Test all servers
.\.claude\tools\test-mcp-servers.ps1

# Or check individual servers
claude mcp list
claude mcp test serena

Quick Test

# In Claude Code
> "Use Serena to find the UserService class"
> "Create a knowledge graph of the authentication flow"
> "Get the latest React documentation"

---

Installation & Setup

Prerequisites

The setup script checks for and guides installation of:

1. Node.js (v18+) - For npm-based servers

   • Download: https://nodejs.org/

2. Python 3 (3.8+) - For Python-based servers

   • Download: https://www.python.org/

3. uv - Python package manager

   • Auto-installed by setup script
   • Manual: curl -LsSf https://astral.sh/uv/install.sh | sh

4. Git (optional, recommended)

   • For cloning repositories
   • Download: https://git-scm.com/

Automated Setup Process

The setup script:

1. ✅ Checks prerequisites
2. ✅ Installs all 8 MCP servers
3. ✅ Creates required directories
4. ✅ Validates configuration
5. ✅ Provides next steps

Time Required: ~5-10 minutes

Manual Installation

If automated setup fails, install servers individually:

Serena

uvx --from "git+https://github.com/oraios/serena" serena --help

Sequential Thinking

npx -y @modelcontextprotocol/server-sequential-thinking

Database Server

npx -y @executeautomation/database-server

Context7

npx -y @upstash/context7-mcp

Memory

npx -y @modelcontextprotocol/server-memory

Fetch

uvx mcp-server-fetch

Windows MCP

git clone https://github.com/lekt9/windows-mcp.git .windows-mcp
cd .windows-mcp
uv sync

Playwright

npx -y @playwright/mcp
npx playwright install  # Install browsers

Post-Setup Configuration

After running setup, configure secrets:

1. Enable MCP Servers

Already configured in .claude/settings.json:

{
  "enableAllProjectMcpServers": true
}

2. Context7 API Key (Optional)

Edit .mcp.json:

"context7": {
  "env": {
    "CONTEXT7_API_KEY": "your-api-key-here"
  }
}

Get key at: https://context7.com/

3. Database Connection (Optional)

Edit .mcp.json:

"database-server": {
  "args": [
    "--server", "your-server",
    "--database", "your-database",
    "--user", "your-username",
    "--password", "your-password",
    "--trustServerCertificate"
  ]
}

4. Restart Claude Code

Close and reopen Claude Code to load servers.

---

Available MCP Servers

1. Serena MCP

Purpose: Semantic code analysis and persistent memory

Type: Python (uvx)

Repository: https://github.com/oraios/serena

Configuration:

{
  "command": "uvx",
  "args": [
    "--from", "git+https://github.com/oraios/serena",
    "serena", "start-mcp-server",
    "--context", "ide-assistant",
    "--project", "Claude Code Setup"
  ]
}

Code Navigation Tools

find_symbol - Locate code symbols by name/pattern

# Find a class
find_symbol("UserService")

# Find with pattern
find_symbol("*Service")

# Find with depth (include methods)
find_symbol("UserService", depth=1, include_body=true)

find_referencing_symbols - Find all references to a symbol

# Find who uses this function
find_referencing_symbols("authenticate", "src/auth/service.ts")

get_symbols_overview - Get file structure

# Get high-level view of file
get_symbols_overview("src/services/user.ts")

search_for_pattern - Search for code patterns

# Find pattern across codebase
search_for_pattern("async.*await", paths_include_glob="**/*.ts")

rename_symbol - Safely rename across codebase

# Rename everywhere
rename_symbol("oldName", "src/file.ts", "newName")

replace_symbol_body - Replace function/class body

# Replace entire method
replace_symbol_body("methodName", "src/file.ts", new_body)

insert_after_symbol / insert_before_symbol - Add code

# Add new method after existing one
insert_after_symbol("existingMethod", "src/file.ts", new_method_code)

Persistent Memory Tools

Storage: .serena/memories/ (survives across sessions)

write_memory - Store persistent project information

write_memory("adr-001-architecture", "Decision: Use microservices...")

read_memory - Recall stored information

read_memory("adr-001-architecture")

list_memories - Browse all memories

list_memories()

delete_memory - Remove outdated information

delete_memory("outdated-info")

Use Serena Memory For

✅ Long-term project knowledge:

• Architectural Decision Records (ADRs)
• Code review findings and summaries
• Lessons learned from implementations
• Project-specific patterns discovered
• Technical debt registry
• Security audit results
• Performance optimization notes
• Migration documentation
• Incident post-mortems

❌ Do NOT use for:

• Temporary analysis state
• Current conversation context
• Session-specific tracking

Memory File Naming Conventions

ADRs (Architectural Decision Records):

adr-001-database-choice-postgresql
adr-002-authentication-jwt-strategy
adr-003-api-versioning-approach

Code Reviews:

code-review-2024-10-15-payment-service
code-review-2025-10-20-auth-refactor

Lessons Learned:

lesson-async-error-handling
lesson-database-connection-pooling
lesson-api-rate-limiting

Patterns:

pattern-repository-implementation
pattern-error-response-format
pattern-logging-strategy

Technical Debt:

debt-legacy-api-authentication
debt-payment-service-refactor-needed

Security:

security-audit-2024-10-full
security-vulnerability-xss-fixed
security-pattern-input-validation

Performance:

performance-optimization-query-caching
performance-analysis-api-endpoints

---

2. Sequential Thinking MCP

Purpose: Chain-of-thought reasoning for complex problems

Type: Node.js (npx)

Package: @modelcontextprotocol/server-sequential-thinking

Configuration:

{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
}

Capabilities

sequentialthinking - Multi-step reasoning tool

Features:

• Dynamic thought count adjustment
• Revision of previous thoughts
• Branch exploration
• Hypothesis generation and verification
• Flexible problem-solving

Parameters:

• thought - Current thinking step
• thought_number - Current step number
• total_thoughts - Estimated total (adjustable)
• next_thought_needed - Continue or stop
• is_revision - Is this revising previous thought
• branch_id - Identifier for exploration branches

Use Cases

✅ Best for:

• Complex architectural decisions
• Multi-step debugging
• Design pattern selection
• Security threat analysis
• Algorithm optimization
• System design problems

Example Flow:

1. Start with initial estimate of needed thoughts
2. Work through problem step-by-step
3. Revise previous thoughts if needed
4. Adjust total thoughts as understanding deepens
5. Generate hypothesis
6. Verify hypothesis
7. Provide final answer

---

3. Database Server MCP

Purpose: SQL Server database interaction

Type: Node.js (npx)

Package: @executeautomation/database-server

Configuration:

{
  "command": "npx",
  "args": [
    "-y", "@executeautomation/database-server",
    "--sqlserver",
    "--server", "your-server",
    "--database", "your-database",
    "--user", "your-username",
    "--password", "your-password",
    "--trustServerCertificate"
  ]
}

Available Tools

read_query - Execute SELECT queries

SELECT * FROM Users WHERE active = 1

write_query - Execute INSERT, UPDATE, DELETE

UPDATE Users SET last_login = GETDATE() WHERE id = 123

create_table - Create new tables

CREATE TABLE Products (
  id INT PRIMARY KEY,
  name VARCHAR(255),
  price DECIMAL(10,2)
)

alter_table - Modify table schema

ALTER TABLE Products ADD description TEXT

drop_table - Remove tables (with confirmation)

drop_table("old_table", confirm=true)

list_tables - Get all tables in database

list_tables()

describe_table - View table schema

describe_table("Users")

export_query - Export results to CSV/JSON

export_query("SELECT * FROM Users", format="csv")

append_insight - Add business insight to memo

append_insight("Sales increased 20% after new feature")

list_insights - View all insights

list_insights()

Use Cases

✅ Best for:

• Database schema exploration
• Query development and testing
• Data analysis
• Business intelligence
• Database migrations
• Performance testing

---

4. Context7 MCP

Purpose: Real-time library documentation access

Type: Node.js (npx)

Package: @upstash/context7-mcp

Website: https://context7.com/

Configuration:

{
  "command": "npx",
  "args": ["-y", "@upstash/context7-mcp"],
  "env": {
    "CONTEXT7_API_KEY": "your-api-key-here"
  }
}

Available Tools

resolve-library-id - Find library identifier

# Find library ID
resolve-library-id("react")
# Returns: "/facebook/react"

resolve-library-id("next.js")
# Returns: "/vercel/next.js"

Selection Criteria:

• Name similarity (exact matches prioritized)
• Description relevance
• Documentation coverage (code snippets count)
• Trust score (7-10 prioritized)

get-library-docs - Get current documentation

# Get React docs
get-library-docs("/facebook/react", topic="hooks")

# Get specific version
get-library-docs("/vercel/next.js/v14.3.0", topic="routing")

# Control token usage
get-library-docs("/mongodb/docs", tokens=10000)

Parameters:

• context7CompatibleLibraryID - Library ID from resolve-library-id
• topic - Focus area (optional)
• tokens - Max tokens (default: 5000)

Use Cases

✅ Best for:

• Learning new frameworks
• Getting up-to-date API references
• Finding best practices
• Code examples from official docs
• Version-specific documentation

Example Workflow:

# 1. Find library
resolve-library-id("supabase")

# 2. Get docs
get-library-docs("/supabase/supabase", topic="authentication")

# 3. Use in code
# Claude now has current Supabase auth docs

---

5. Memory MCP (Knowledge Graph)

Purpose: Temporary in-memory knowledge graph

Type: Node.js (npx)

Package: @modelcontextprotocol/server-memory

Storage: In-memory, cleared after session ends

Configuration:

{
  "command": "powershell",
  "args": [
    "-ExecutionPolicy", "Bypass",
    "-File", ".\.claude\tools\start-memory.ps1"
  ]
}

Available Tools

create_entities - Create entities in graph

create_entities([
  {
    name: "PaymentService",
    entityType: "Service",
    observations: [
      "Handles Stripe integration",
      "Located in src/services/payment.ts",
      "Depends on DatabaseService"
    ]
  },
  {
    name: "UserAuthentication",
    entityType: "Feature",
    observations: [
      "Uses JWT tokens",
      "Session timeout: 24 hours"
    ]
  }
])

create_relations - Define relationships

create_relations([
  {
    from: "PaymentService",
    to: "DatabaseService",
    relationType: "depends_on"
  },
  {
    from: "UserAuthentication",
    to: "SessionManager",
    relationType: "uses"
  }
])

add_observations - Add details to entities

add_observations([
  {
    entityName: "PaymentService",
    contents: [
      "Implemented retry logic",
      "Added webhook support"
    ]
  }
])

search_nodes - Search knowledge graph

search_nodes("payment")

read_graph - View entire graph

read_graph()

open_nodes - Retrieve specific entities

open_nodes(["PaymentService", "UserAuthentication"])

delete_entities - Remove entities

delete_entities(["OldFeature"])

delete_relations - Remove relationships

delete_relations([
  {from: "A", to: "B", relationType: "uses"}
])

delete_observations - Remove specific observations

delete_observations([
  {
    entityName: "PaymentService",
    observations: ["outdated info"]
  }
])

Use Cases

✅ Best for:

• Current conversation context
• Temporary analysis during task
• Entity relationships in current work
• Cross-file refactoring state (temporary)
• Session-specific tracking

❌ Do NOT use for:

• Long-term knowledge (use Serena instead)
• ADRs or lessons learned
• Project patterns
• Anything needed next week

Memory vs Serena Decision Tree

Question: Should this information exist next week?

• YES → Use Serena write_memory
• NO → Use Memory graph

Storage Location: .memory-mcp/knowledge_graph.json (managed by PowerShell script)

---

6. Fetch MCP

Purpose: Web content retrieval and conversion

Type: Python (uvx)

Package: mcp-server-fetch

Configuration:

{
  "command": "uvx",
  "args": ["mcp-server-fetch"]
}

Available Tools

fetch - Retrieve and process URLs

Parameters:

• url - URL to fetch (required)
• max_length - Max characters (default: 5000)
• start_index - Start position (for pagination)
• raw - Get raw HTML instead of markdown

Features:

• Converts HTML to markdown
• Pagination support for long content
• Automatic HTTPS upgrade
• Self-cleaning 15-minute cache

Examples:

# Fetch documentation
fetch("https://docs.example.com/api")

# Get raw HTML
fetch("https://example.com", raw=true)

# Paginated content
fetch("https://long-page.com", start_index=5000, max_length=5000)

Use Cases

✅ Best for:

• API documentation scraping
• Web content analysis
• Integration documentation
• Blog post research
• Technical article retrieval

Note: When URL redirects to different host, tool informs you. Make new request with redirect URL.

---

7. Windows MCP

Purpose: Windows desktop automation

Type: Python (uv)

Repository: https://github.com/lekt9/windows-mcp

Platform: Windows only (won't affect other servers on Mac/Linux)

Configuration:

{
  "command": "uv",
  "args": [
    "--directory", "./.windows-mcp",
    "run", "main.py"
  ]
}

Available Tools

Launch-Tool - Launch applications

Launch-Tool("notepad")
Launch-Tool("calculator")
Launch-Tool("chrome")

Powershell-Tool - Execute PowerShell commands

Powershell-Tool("Get-Process | Where-Object {$_.Name -like 'chrome*'}")

State-Tool - Capture desktop state

# Get UI elements, focused apps, interactive elements
State-Tool(use_vision=false)

# Include visual screenshot
State-Tool(use_vision=true)

Clipboard-Tool - Clipboard operations

# Copy text
Clipboard-Tool(mode="copy", text="Hello World")

# Paste (retrieve)
Clipboard-Tool(mode="paste")

Click-Tool - Click UI elements

# Left click at coordinates
Click-Tool(loc=[100, 200])

# Right click
Click-Tool(loc=[100, 200], button="right")

# Double click
Click-Tool(loc=[100, 200], clicks=2)

Type-Tool - Type text into fields

# Type text (append)
Type-Tool(loc=[100, 200], text="Hello")

# Clear and type
Type-Tool(loc=[100, 200], text="Hello", clear=true)

# Type and press Enter
Type-Tool(loc=[100, 200], text="search query", press_enter=true)

Resize-Tool - Resize/move windows

# Resize window
Resize-Tool(size=[800, 600])

# Move window
Resize-Tool(loc=[100, 100])

Switch-Tool - Switch to application

Switch-Tool("notepad")
Switch-Tool("chrome")

Scroll-Tool - Scroll content

# Scroll down at location
Scroll-Tool(loc=[400, 300], direction="down", wheel_times=3)

# Scroll horizontally
Scroll-Tool(type="horizontal", direction="right")

Drag-Tool - Drag and drop

Drag-Tool(from_loc=[100, 100], to_loc=[200, 200])

Move-Tool - Move mouse cursor

Move-Tool(to_loc=[300, 400])

Shortcut-Tool - Keyboard shortcuts

# Copy
Shortcut-Tool(["ctrl", "c"])

# Alt+Tab
Shortcut-Tool(["alt", "tab"])

# Windows+R
Shortcut-Tool(["win", "r"])

Key-Tool - Press individual keys

Key-Tool("enter")
Key-Tool("escape")
Key-Tool("f5")

Wait-Tool - Pause execution

Wait-Tool(duration=5)  # Wait 5 seconds

Scrape-Tool - Scrape webpage to markdown

Scrape-Tool("https://example.com")

Use Cases

✅ Best for:

• GUI automation
• Desktop testing
• Windows-specific operations
• Application interaction
• Screen automation workflows

---

8. Playwright MCP

Purpose: Browser automation and testing

Type: Node.js (npx)

Package: @playwright/mcp

Website: https://playwright.dev/

Configuration:

{
  "command": "npx",
  "args": ["-y", "@playwright/mcp"]
}

Additional Setup: Run npx playwright install to install browsers

Available Tools

Navigation:

• browser_navigate - Navigate to URL
• browser_navigate_back - Go back

Interaction:

• browser_click - Click elements
• browser_type - Type text
• browser_fill_form - Fill multiple form fields
• browser_select_option - Select dropdown options
• browser_hover - Hover over elements
• browser_drag - Drag and drop

Keyboard:

• browser_press_key - Press keys
• browser_evaluate - Execute JavaScript

Capture:

• browser_snapshot - Accessibility snapshot (better than screenshot)
• browser_take_screenshot - Take visual screenshot

Monitoring:

• browser_console_messages - Get console logs
• browser_network_requests - View network traffic

Window Management:

• browser_tabs - Manage tabs (list, create, close, select)
• browser_resize - Resize browser window
• browser_close - Close browser

Advanced:

• browser_file_upload - Upload files
• browser_handle_dialog - Handle alerts/confirms
• browser_wait_for - Wait for conditions

Usage Examples

Basic Navigation:

// Navigate and capture
browser_navigate("https://example.com")
browser_snapshot()

// Take screenshot
browser_take_screenshot(filename="page.png")

Form Interaction:

// Fill form
browser_fill_form([
  {name: "username", type: "textbox", ref: "input#user", value: "john"},
  {name: "password", type: "textbox", ref: "input#pass", value: "secret"},
  {name: "remember", type: "checkbox", ref: "input#rem", value: "true"}
])

// Click submit
browser_click(element="Submit button", ref="button[type='submit']")

Testing Workflow:

// 1. Navigate
browser_navigate("https://app.example.com/login")

// 2. Fill and submit
browser_type(element="Username field", ref="input#user", text="test@example.com")
browser_type(element="Password field", ref="input#pass", text="password")
browser_click(element="Login button", ref="button.login")

// 3. Wait and verify
browser_wait_for(text="Welcome")
browser_snapshot()

// 4. Check network
browser_network_requests()

Tab Management:

// List tabs
browser_tabs(action="list")

// Create new tab
browser_tabs(action="new")

// Switch to tab
browser_tabs(action="select", index=1)

// Close tab
browser_tabs(action="close", index=2)

Use Cases

✅ Best for:

• E2E testing
• Web scraping
• UI automation
• Browser-based workflows
• Screenshot capture
• Network monitoring
• Console debugging

---

Usage Guide

Quick Decision Tree

Need to navigate code? → Use Serena code functions

Need to store knowledge long-term? → Use Serena write_memory

Building temporary context for current task? → Use Memory graph

Need current library docs? → Use Context7

Complex problem requiring deep thought? → Use Sequential Thinking

Need to automate browser? → Use Playwright

Need Windows desktop automation? → Use Windows MCP

Need to query database? → Use Database Server

Need to scrape web content? → Use Fetch

Usage by Agent Type

Architect Agent

## MCP Usage

**Serena**:
- `get_symbols_overview` - Understand current architecture
- `find_symbol` - Locate key components
- `write_memory` - Store ADRs:
  - "adr-001-microservices-architecture"
  - "adr-002-database-choice-postgresql"

**Memory**:
- `create_entities` - Components being designed
- `create_relations` - Model dependencies
- `add_observations` - Document design rationale

Note: After design finalized, store in Serena memory as ADR

Code Reviewer Agent

## MCP Usage

**Serena**:
- `find_symbol` - Locate reviewed code
- `find_referencing_symbols` - Impact analysis
- `write_memory` - Store review findings:
  - "code-review-2024-10-payment-service"

**Memory**:
- `create_entities` - Issues found (Critical, Warning, Suggestion)
- `create_relations` - Link issues to code locations
- `add_observations` - Fix recommendations

Note: Summary stored in Serena memory after review

Security Analyst Agent

## MCP Usage

**Serena**:
- `find_symbol` - Locate security-sensitive code
- `search_for_pattern` - Find potential vulnerabilities
- `write_memory` - Store audit results:
  - "security-audit-2024-10-full-scan"
  - "vulnerability-sql-injection-fixed"

**Memory**:
- `create_entities` - Vulnerabilities found
- `create_relations` - Link to affected code
- `add_observations` - Document severity and remediation

Test Engineer Agent

## MCP Usage

**Serena**:
- `find_symbol` - Locate code to test
- `find_referencing_symbols` - Understand dependencies
- `write_memory` - Store test patterns:
  - "test-pattern-async-handlers"
  - "test-pattern-database-mocking"

**Memory**:
- `create_entities` - Test cases being generated
- `create_relations` - Link tests to code under test

**Playwright**:
- Browser testing automation

Usage in Slash Commands

/implement Command

## MCP Usage

**Serena**:
- `find_symbol` - Locate existing patterns
- `find_referencing_symbols` - Understand dependencies
- `rename_symbol` - Refactor safely
- `write_memory` - Store lessons:
  - "lesson-payment-integration-stripe"
  - "pattern-error-handling-async"

**Memory**:
- `create_entities` - Track features being implemented
- `create_relations` - Model integration points

**Context7**:
- `get-library-docs` - Current framework docs

/analyze Command

## MCP Usage

**Serena**:
- `get_symbols_overview` - Understand structure
- `find_symbol` - Locate complex code
- `search_for_pattern` - Find duplicates
- `write_memory` - Store findings:
  - "analysis-2024-10-technical-debt"
  - "analysis-complexity-hotspots"

**Memory**:
- `create_entities` - Files/functions analyzed
- `create_relations` - Model dependencies
- `add_observations` - Document metrics

---

Configuration

Main Configuration File

Location: .mcp.json (project root)

Format:

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/oraios/serena",
        "serena", "start-mcp-server",
        "--context", "ide-assistant",
        "--project", "ProjectName"
      ]
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    },
    "database-server": {
      "command": "npx",
      "args": [
        "-y", "@executeautomation/database-server",
        "--sqlserver",
        "--server", "server-name",
        "--database", "db-name",
        "--user", "username",
        "--password", "password",
        "--trustServerCertificate"
      ]
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": {
        "CONTEXT7_API_KEY": "your-key"
      }
    },
    "memory": {
      "command": "powershell",
      "args": [
        "-ExecutionPolicy", "Bypass",
        "-File", ".\.claude\tools\start-memory.ps1"
      ]
    },
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    "windows-mcp": {
      "command": "uv",
      "args": [
        "--directory", "./.windows-mcp",
        "run", "main.py"
      ]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    }
  }
}

Claude Settings Configuration

Location: .claude/settings.json

Enable MCP Servers:

{
  "enableAllProjectMcpServers": true
}

Enable Specific Servers:

{
  "mcpServers": {
    "serena": {"enabled": true},
    "memory": {"enabled": true},
    "context7": {"enabled": true}
  }
}

Environment Variables

Context7 API Key:

# Option 1: In .mcp.json (not recommended for git)
"env": {"CONTEXT7_API_KEY": "ctx7sk-..."}

# Option 2: System environment variable (recommended)
export CONTEXT7_API_KEY="ctx7sk-..."

Database Credentials:

# Use environment variables for security
export DB_SERVER="server-name"
export DB_USER="username"
export DB_PASSWORD="password"

# Reference in .mcp.json
"args": ["--server", "${DB_SERVER}", "--user", "${DB_USER}"]

---

Best Practices

Memory Management

Use Serena Memory For:

• ✅ Architectural Decision Records
• ✅ Code review summaries
• ✅ Lessons learned
• ✅ Project patterns
• ✅ Technical debt tracking
• ✅ Security findings
• ✅ Performance notes

Use Memory Graph For:

• ✅ Current conversation context
• ✅ Temporary analysis state
• ✅ Session-specific tracking
• ✅ Cross-file refactoring state

DON'T Mix Them:

• ❌ Don't store temporary info in Serena
• ❌ Don't expect Memory graph to persist

Code Navigation Efficiency

Good Practice (efficient):

# 1. Get overview first
get_symbols_overview("src/service.ts")

# 2. Target specific symbols
find_symbol("UserService/authenticate", include_body=true)

# 3. Find references if needed
find_referencing_symbols("authenticate", "src/service.ts")

Bad Practice (wasteful):

# Reading entire files unnecessarily
Read("src/service.ts")  # 1000 lines
Read("src/utils.ts")    # 500 lines
Read("src/auth.ts")     # 800 lines

Documentation Lookup Pattern

Correct Workflow:

# 1. Always resolve library ID first
resolve-library-id("react")
# Returns: /facebook/react

# 2. Then get docs
get-library-docs("/facebook/react", topic="hooks")

Incorrect (won't work):

# Don't skip resolve step
get-library-docs("react")  # ERROR: not a valid ID

Browser Automation Best Practices

Use Snapshots, Not Screenshots:

# Good: Accessibility snapshot (faster, more data)
browser_snapshot()

# Use screenshots only when visual verification needed
browser_take_screenshot()

Wait for Content:

# Good: Wait for specific text
browser_wait_for(text="Welcome")

# Avoid arbitrary delays
browser_wait_for(time=5)  # Use only when necessary

Database Query Safety

Always Use Parameterized Queries:

-- Good
SELECT * FROM Users WHERE id = @userId

-- Bad (SQL injection risk)
SELECT * FROM Users WHERE id = ${userInput}

Test Before Write:

# 1. Test with read_query
read_query("SELECT * FROM Users WHERE ...")

# 2. Verify results

# 3. Then write_query
write_query("UPDATE Users SET ...")

---

Troubleshooting

MCP Server Not Starting

Problem: Server fails to connect

Solutions:

1. Check .mcp.json syntax:

   cat .mcp.json | jq .
   

2. Test command manually:

   npx -y @modelcontextprotocol/server-memory
   uvx mcp-server-fetch
   

3. Check Claude Code logs:

   • Windows: .claude\logs\
   • Linux/Mac: .claude/logs/

4. Verify prerequisites installed:

   node --version  # Should be 18+
   python --version  # Should be 3.8+
   npm --version
   uv --version
   

5. Restart Claude Code after config changes

Serena Memory Not Persisting

Problem: Memories disappear between sessions

Check:

1. Verify storage location exists:

   ls .serena/memories/
   

2. Check memory was actually written:

   list_memories()
   

3. Ensure using write_memory, not Memory graph:

   # Correct (persists)
   write_memory("my-memory", "content")
   
   # Wrong (session only)
   create_entities([{name: "my-memory", ...}])
   

Memory Graph Empty After Restart

This is normal! Memory graph is session-only storage.

If you need persistence: Use Serena write_memory instead.

Context7 Not Working

Problem: Library docs not retrieved

Solutions:

1. Check API key configured:

   cat .mcp.json | jq '.mcpServers.context7.env'
   

2. Get free API key: https://context7.com/

3. Always resolve library ID first:

   # Required first step
   resolve-library-id("library-name")
   

4. Use correct ID format:

   # Correct
   get-library-docs("/facebook/react")
   
   # Wrong
   get-library-docs("react")
   

Playwright Browsers Not Installed

Problem: Browser automation fails

Solution:

npx playwright install
npx playwright install chromium  # Just Chromium

Verify:

npx playwright --version

Windows MCP Not Working on Mac/Linux

This is normal! Windows MCP is Windows-only.

It won't break other servers - they'll continue working.

On Mac/Linux: Simply ignore Windows MCP server errors.

Database Connection Failed

Problem: Cannot connect to SQL Server

Solutions:

1. Verify connection details:

   # Test connection manually
   sqlcmd -S server -U user -P password -d database
   

2. Check .mcp.json configuration:

   "--server", "correct-server-name",
   "--database", "correct-db-name",
   "--user", "correct-username",
   "--password", "correct-password"
   

3. Add --trustServerCertificate if using self-signed certs

4. Check network connectivity and firewall rules

Permission Errors

Problem: MCP server command denied

Solutions:

1. Check file permissions:

   # Linux/Mac
   chmod +x .claude/tools/*.sh
   
   # Windows PowerShell
   Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
   

2. Verify tool allowed in .claude/settings.json:

   {
     "permissions": {
       "allowed": ["mcp__serena__*", "mcp__memory__*"]
     }
   }
   

Command Not Found (npx/uvx)

Problem: Setup script can't find package managers

Solutions:

1. Install Node.js: https://nodejs.org/

2. Install Python and uv:

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

3. Restart terminal after installation

4. Verify installation:

   npx --version
   uvx --version
   

---

Advanced Topics

Custom MCP Server Configuration

You can add your own MCP servers to .mcp.json:

{
  "mcpServers": {
    "my-custom-server": {
      "command": "node",
      "args": ["./my-server/index.js"],
      "env": {
        "MY_CONFIG": "value"
      }
    }
  }
}

MCP Server Development

Create custom MCP servers:

• Documentation: https://modelcontextprotocol.io/
• SDK: https://github.com/modelcontextprotocol/servers
• Examples: https://github.com/modelcontextprotocol/servers/tree/main/src

Performance Optimization

Parallel MCP Calls:

# Claude can call multiple MCP servers in parallel
# when operations are independent

Token Efficiency:

• Use Serena symbols instead of full file reads
• Use Memory graph for temporary context
• Leverage Grep/Glob before reading

Caching:

• Context7 and Fetch have built-in caching
• Memory graph caches for session duration

Security Considerations

Secrets Management:

• ❌ Never commit API keys to git
• ✅ Use environment variables
• ✅ Use .claude/settings.local.json (gitignored)

Database Access:

• Use read-only accounts when possible
• Parameterize all queries
• Audit database operations

Browser Automation:

• Be cautious with authentication in Playwright
• Don't expose credentials in screenshots
• Review captured network requests

Integration with CI/CD

Headless Mode (optional):

# Run Claude Code in CI pipeline
claude --headless --session ci-build

# Use MCP servers in automation
# Example: Database migrations, E2E tests

Updating MCP Servers

Update All Servers:

# Re-run setup script (idempotent)
.\.claude\tools\setup-all-mcp-servers.ps1

Update Individual Server:

# npm-based servers (auto-update with -y flag)
npx -y @modelcontextprotocol/server-memory

# Python-based servers
uvx --from "git+https://github.com/oraios/serena" serena

# Windows MCP (git-based)
cd .windows-mcp
git pull
uv sync

Monitoring and Logging

Check Server Status:

claude mcp list
claude mcp test <server-name>

View Logs:

# All logs
ls .claude/logs/

# MCP-specific logs
cat .claude/logs/mcp-*.log

Debug Mode: Add to .claude/settings.json:

{
  "debug": true,
  "logLevel": "debug"
}

---

Additional Resources

Official Documentation

• Claude Code: https://docs.claude.com/en/docs/claude-code/
• MCP Specification: https://modelcontextprotocol.io/
• Serena: https://github.com/oraios/serena
• Context7: https://context7.com/
• Playwright: https://playwright.dev/

Project Documentation

• Quick Start: QUICKSTART.md
• Complete Setup: CLAUDE_CODE_SETUP_COMPLETE.md
• Usage Templates: .claude/agents/MCP_USAGE_TEMPLATES.md

Setup Scripts

• Windows Setup: .claude/tools/setup-all-mcp-servers.ps1
• Linux/Mac Setup: .claude/tools/setup-all-mcp-servers.sh
• Test Script: .claude/tools/test-mcp-servers.ps1

---

Summary

This guide covers all 8 MCP servers configured in this project:

1. ✅ Serena - Code navigation + persistent memory
2. ✅ Sequential Thinking - Complex reasoning
3. ✅ Database Server - SQL Server integration
4. ✅ Context7 - Library documentation
5. ✅ Memory - Knowledge graph (session)
6. ✅ Fetch - Web content retrieval
7. ✅ Windows MCP - Desktop automation
8. ✅ Playwright - Browser automation

Quick Commands Reference

# Setup
.\.claude\tools\setup-all-mcp-servers.ps1

# Test
.\.claude\tools\test-mcp-servers.ps1

# Check status
claude mcp list
claude mcp test <server-name>

# View logs
cat .claude/logs/mcp-*.log

Key Takeaways

• Serena Memory = Long-term knowledge (persists)
• Memory Graph = Session-only context (temporary)
• Context7 = Real-time library docs (requires API key)
• Playwright = Browser automation (requires browser install)
• Windows MCP = Windows-only (safe to ignore on Mac/Linux)

---

Version: 1.0.0 Last Updated: 2025-10-20 Maintained by: Claude Code Setup Project

For latest information: See official documentation at https://docs.claude.com/en/docs/claude-code/

---

This comprehensive guide consolidates all MCP server documentation from multiple sources into a single reference. For setup automation, see the tools in .claude/tools/.