# Tool Integration Benefits

1. **Standardized Interface**
   - Single protocol for diverse tools
   - Consistent authentication patterns
   - Unified error handling

2. **Context Preservation**
   - Persistent connections to data sources
   - Reduced token usage (no re-explaining context)
   - Seamless multi-step operations

3. **Extensibility**
   - Custom MCP servers for internal tools
   - Community-contributed servers
   - Easy addition of new capabilities

4. **Security**
   - Credentials isolated from prompts
   - Environment variable-based authentication
   - Scoped permissions per server

5. **Performance**
   - Direct tool access (no prompt-based workarounds)
   - Streaming support for large responses
   - Parallel tool execution

# Claude Code MCP configuration
~/.claude.json

# Structure
{
  "mcpServers": {
    "server-name": {
      "type": "stdio",
      "command": "command-to-run",
      "args": ["arg1", "arg2"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}

# Backup and version control
cp ~/.claude.json ~/.claude.json.backup
git add ~/.claude.json
git commit -m "Update MCP configuration"

# Share configuration across team
# Store in team repository (with placeholder secrets)
cp team-mcp-config.json ~/.claude.json
# Then add real secrets via environment variables

{
  "mcpServers": {
    "sequential-thinking": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    },
    "memory": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
      "args": ["/Users/username/projects"]
    }
  }
}

# Check MCP server status in Claude Code
/mcp

# Expected output:
# Connected MCP Servers:
# ✓ sequential-thinking
# ✓ memory
# ✓ filesystem

# Test server connectivity
# In Claude Code chat:
"Use the sequential-thinking MCP to analyze this problem step by step"

# Restart Claude Code after configuration changes
# macOS: Cmd+Q then reopen
# Linux: Close and restart application
# Windows: Exit and relaunch

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

# Complex Problem Solving
"Use sequential thinking to design a database schema for a multi-tenant SaaS application with these requirements:
- 100k tenants
- Tenant data isolation (compliance requirement)
- Shared infrastructure for cost efficiency
- Sub-100ms query performance"

# Architecture Planning
"Use sequential thinking to plan the migration from monolith to microservices:
- Current: Django monolith (200k LOC)
- Target: Microservices architecture
- Constraint: Zero downtime
- Timeline: 6 months"

# Debugging Complex Issues
"Use sequential thinking to debug why database connections are exhausted under load"

{
  "mcpServers": {
    "memory": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

# Cross-Session Context
"Store this architecture decision in memory:
- Decision: Use PostgreSQL JSONB for flexible product attributes
- Rationale: 1000+ different product types, each with unique attributes
- Date: 2025-01-20
- Alternatives considered: NoSQL (rejected for transaction requirements)"

# Project Knowledge Base
"Remember these API endpoints for the e-commerce platform:
- POST /api/v1/products - Create product
- GET /api/v1/products/{id} - Get product details
- PUT /api/v1/products/{id} - Update product
- DELETE /api/v1/products/{id} - Delete product"

# Team Conventions
"Store coding conventions:
- Use async/await for all I/O operations
- Pydantic models for all API contracts
- pytest for testing (not unittest)
- black + isort for code formatting"

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

# Generate GitHub Personal Access Token
# Settings → Developer settings → Personal access tokens → Tokens (classic)
# Scopes needed: repo, read:org, read:user

# Add to environment
export GITHUB_TOKEN="ghp_yourtokenhere"

# Or use .env file
echo "GITHUB_TOKEN=ghp_yourtokenhere" >> ~/.env
source ~/.env

# Issue Management
"List all open issues labeled 'bug' in supporttools/website repository"

"Create a new issue:
Title: Add user authentication to API
Labels: enhancement, priority-high
Body: Implement JWT-based authentication with refresh tokens"

# Pull Request Management
"Show all open pull requests in the main repository"

"Create a pull request:
Title: Implement product search feature
Source: feature/product-search
Target: main
Body: Adds full-text search with PostgreSQL"

# Repository Analysis
"Analyze the last 50 commits to identify the most frequently modified files"

"Show contributors and their commit counts for the last 3 months"

# CI/CD Integration
"Check the status of the latest GitHub Actions workflow"

"Show failed test results from the last CI run"

{
  "mcpServers": {
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "${DATABASE_URL}"
      }
    },
    "sqlite": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite"],
      "args": ["/path/to/database.db"]
    }
  }
}

# Schema Analysis
"Show me the schema for the users and orders tables"

"Identify missing indexes on foreign key columns"

# Query Optimization
"Explain this query and suggest optimizations:
SELECT * FROM products p
JOIN categories c ON p.category_id = c.id
WHERE c.name = 'Electronics'"

# Data Exploration
"Show the top 10 products by sales volume from the last 30 days"

"Find duplicate email addresses in the users table"

# Migration Assistance
"Generate a migration to add email_verified column to users table"

"Create indexes for the most common WHERE clause columns"

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
      "args": ["/Users/username/projects", "/Users/username/documents"]
    }
  }
}

# File Search
"Find all Python files in the project that import requests library"

"List all configuration files (.yml, .yaml, .json, .toml)"

# Code Analysis
"Analyze all files in the api/ directory and identify duplicate code"

"Find all TODO comments in TypeScript files"

# Documentation
"Read all markdown files and create a table of contents"

"Find undocumented Python functions (missing docstrings)"

{
  "mcpServers": {
    "omnisearch": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-omnisearch"],
      "env": {
        "TAVILY_API_KEY": "${TAVILY_API_KEY}",
        "BRAVE_API_KEY": "${BRAVE_API_KEY}",
        "SERPER_API_KEY": "${SERPER_API_KEY}",
        "SERPAPI_API_KEY": "${SERPAPI_API_KEY}",
        "SEARCHAPI_API_KEY": "${SEARCHAPI_API_KEY}",
        "GOOGLE_SEARCH_API_KEY": "${GOOGLE_SEARCH_API_KEY}",
        "GOOGLE_CSE_ID": "${GOOGLE_CSE_ID}"
      }
    }
  }
}

# .env file for search APIs
TAVILY_API_KEY=tvly-xxxxx
BRAVE_API_KEY=BSA-xxxxx
SERPER_API_KEY=xxxxx
SERPAPI_API_KEY=xxxxx
SEARCHAPI_API_KEY=xxxxx
GOOGLE_SEARCH_API_KEY=xxxxx
GOOGLE_CSE_ID=xxxxx

# Load environment variables
source ~/.env

# Or use direnv for automatic loading
echo "dotenv" > .envrc
direnv allow

# Technical Documentation
"Search for the latest FastAPI documentation on background tasks"

"Find best practices for PostgreSQL connection pooling in production"

# Troubleshooting
"Search for solutions to 'connection pool exhausted' errors in asyncpg"

"Find GitHub issues related to JWT token refresh race conditions"

# Research
"Search for benchmarks comparing Redis vs Memcached for session storage"

"Find case studies on migrating from MySQL to PostgreSQL"

{
  "mcpServers": {
    "brave-search": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    }
  }
}

# Get Brave Search API key
# Visit: https://brave.com/search/api/
# Sign up for API access

# Add to environment
export BRAVE_API_KEY="BSA-xxxxxxxxxxxxx"

# Test API key
curl -H "X-Subscription-Token: $BRAVE_API_KEY" \
  "https://api.search.brave.com/res/v1/web/search?q=fastapi+tutorials"

{
  "mcpServers": {
    "puppeteer": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

# UI Testing
"Navigate to http://localhost:3000 and verify the login form is present"

"Fill out the registration form with test data and submit"

# Screenshot Generation
"Take a screenshot of the product listing page at http://localhost:3000/products"

"Capture the checkout flow across multiple screen sizes"

# Web Scraping
"Navigate to the API documentation and extract all endpoint URLs"

"Get the pricing information from competitor website (for comparison)"

# Integration Testing
"Test the complete user registration flow:
1. Fill registration form
2. Submit and verify redirect
3. Check email verification sent
4. Verify database entry created"

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-playwright"]
    }
  }
}

# Cross-Browser Testing
"Test the checkout flow in Chrome, Firefox, and Safari"

# Mobile Responsiveness
"Test the product page on iPhone 13 and iPad Pro viewports"

# Performance Monitoring
"Measure page load time and Core Web Vitals for the homepage"

# Accessibility Testing
"Run accessibility audit on the dashboard page and report violations"

{
  "mcpServers": {
    "slack": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
        "SLACK_TEAM_ID": "${SLACK_TEAM_ID}"
      }
    }
  }
}

# Create Slack App
# Visit: https://api.slack.com/apps
# Create New App → From scratch
# Add Bot Token Scopes:
#   - channels:read
#   - chat:write
#   - users:read
#   - channels:history

# Install to workspace and get tokens
export SLACK_BOT_TOKEN="xoxb-xxxxxxxxxxxxx"
export SLACK_TEAM_ID="T01XXXXXXXXX"

# Notifications
"Send a message to #deployments channel: 'Production deployment completed successfully'"

# Team Communication
"Post a summary of today's code changes to #engineering channel"

# Incident Response
"Send critical alert to #incidents: 'Database connection pool exhausted, investigating'"

# Automated Reporting
"Post daily test coverage report to #qa channel"

// custom-mcp-server.ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";

const server = new Server(
  {
    name: "custom-api-server",
    version: "1.0.0",
  },
  {
    capabilities: {
      tools: {},
    },
  }
);

// Define available tools
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "get_user_stats",
        description: "Retrieve user statistics from internal API",
        inputSchema: {
          type: "object",
          properties: {
            user_id: {
              type: "string",
              description: "User ID to fetch stats for",
            },
            period: {
              type: "string",
              enum: ["day", "week", "month"],
              description: "Time period for statistics",
            },
          },
          required: ["user_id"],
        },
      },
      {
        name: "create_deployment",
        description: "Trigger deployment to specified environment",
        inputSchema: {
          type: "object",
          properties: {
            environment: {
              type: "string",
              enum: ["staging", "production"],
              description: "Target environment",
            },
            version: {
              type: "string",
              description: "Version tag to deploy",
            },
          },
          required: ["environment", "version"],
        },
      },
    ],
  };
});

// Handle tool calls
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  switch (request.params.name) {
    case "get_user_stats": {
      const { user_id, period = "week" } = request.params.arguments;

      // Call internal API
      const response = await fetch(
        `https://api.internal.company.com/users/${user_id}/stats?period=${period}`,
        {
          headers: {
            Authorization: `Bearer ${process.env.INTERNAL_API_TOKEN}`,
          },
        }
      );

      const stats = await response.json();

      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(stats, null, 2),
          },
        ],
      };
    }

    case "create_deployment": {
      const { environment, version } = request.params.arguments;

      // Trigger deployment via internal API
      const response = await fetch(
        "https://api.internal.company.com/deployments",
        {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
            Authorization: `Bearer ${process.env.INTERNAL_API_TOKEN}`,
          },
          body: JSON.stringify({ environment, version }),
        }
      );

      const deployment = await response.json();

      return {
        content: [
          {
            type: "text",
            text: `Deployment ${deployment.id} triggered for ${environment} (version ${version})`,
          },
        ],
      };
    }

    default:
      throw new Error(`Unknown tool: ${request.params.name}`);
  }
});

// Start server
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main().catch(console.error);

{
  "name": "custom-mcp-server",
  "version": "1.0.0",
  "type": "module",
  "bin": {
    "custom-mcp-server": "./build/index.js"
  },
  "scripts": {
    "build": "tsc",
    "prepare": "npm run build"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^0.5.0"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "typescript": "^5.0.0"
  }
}

{
  "mcpServers": {
    "custom-api": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/custom-mcp-server/build/index.js"],
      "env": {
        "INTERNAL_API_TOKEN": "${INTERNAL_API_TOKEN}"
      }
    }
  }
}

// ~/.claude.json
{
  "mcpServers": {
    "postgres-dev": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "${DATABASE_URL_DEV}"
      }
    },
    "postgres-staging": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "${DATABASE_URL_STAGING}"
      }
    },
    "postgres-prod-readonly": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "${DATABASE_URL_PROD_READONLY}"
      }
    }
  }
}

# Development Queries
"Use postgres-dev to show the schema for the users table"

# Staging Validation
"Use postgres-staging to verify the migration was applied successfully"

# Production Analysis (Read-Only)
"Use postgres-prod-readonly to count active users in the last 24 hours"

# .env file (never commit)
DATABASE_URL_DEV=postgresql://user:pass@localhost:5432/myapp_dev
DATABASE_URL_STAGING=postgresql://user:pass@staging.db.company.com:5432/myapp
DATABASE_URL_PROD_READONLY=postgresql://readonly:pass@prod-replica.db.company.com:5432/myapp
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
SLACK_BOT_TOKEN=xoxb-xxxxxxxxxxxxxxxxxxxx
INTERNAL_API_TOKEN=xxxxxxxxxxxxxxxxxxxxx

# Load environment variables
source ~/.env

# Or use direnv for automatic loading
cat > .envrc <<EOF
dotenv
EOF

direnv allow

# Verify environment variables loaded
env | grep DATABASE_URL

// team-mcp-config-template.json
// Commit this to repository with placeholder values
{
  "mcpServers": {
    "sequential-thinking": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    },
    "memory": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres-dev": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "${DATABASE_URL_DEV}"
      }
    },
    "slack": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
        "SLACK_TEAM_ID": "${SLACK_TEAM_ID}"
      }
    }
  }
}

#!/bin/bash
# setup-mcp.sh - Team MCP configuration setup

echo "Setting up MCP configuration..."

# 1. Copy template to user config
cp team-mcp-config-template.json ~/.claude.json

# 2. Prompt for secrets
read -p "GitHub Personal Access Token: " GITHUB_TOKEN
read -p "Slack Bot Token: " SLACK_BOT_TOKEN
read -p "Slack Team ID: " SLACK_TEAM_ID
read -p "Dev Database URL: " DATABASE_URL_DEV

# 3. Create .env file
cat > ~/.env <<EOF
GITHUB_TOKEN=$GITHUB_TOKEN
SLACK_BOT_TOKEN=$SLACK_BOT_TOKEN
SLACK_TEAM_ID=$SLACK_TEAM_ID
DATABASE_URL_DEV=$DATABASE_URL_DEV
EOF

# 4. Source environment variables
echo "source ~/.env" >> ~/.bashrc
source ~/.env

echo "✅ MCP configuration complete!"
echo "Restart Claude Code to activate MCP servers"

# Issue: MCP Server Not Connecting

## Check 1: Verify Configuration Syntax
cat ~/.claude.json | jq .
# Should parse without errors

## Check 2: Test MCP Server Directly
npx -y @modelcontextprotocol/server-sequential-thinking
# Should start without errors

## Check 3: Verify Environment Variables
echo $GITHUB_TOKEN
echo $DATABASE_URL
# Should output values (not empty)

## Check 4: Check Claude Code Logs
# macOS: ~/Library/Logs/Claude/
# Linux: ~/.config/Claude/logs/
# Windows: %APPDATA%\Claude\logs\

# Issue: MCP Tools Not Appearing

## Solution: Restart Claude Code
# Configuration changes require restart
# Fully quit (not just close window) and reopen

## Solution: Check /mcp Command
/mcp
# Shows connected servers
# If server missing, check configuration

# Issue: Authentication Errors

## Solution: Verify API Keys
# Test API keys independently
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
  https://api.github.com/user

## Solution: Check Environment Variable Loading
# Add debug logging to MCP server
console.log('GITHUB_TOKEN:', process.env.GITHUB_TOKEN);

# Issue: Performance Degradation

## Solution: Limit Active MCP Servers
# Only enable servers you actively use
# Comment out unused servers

## Solution: Monitor MCP Server Resource Usage
# Check CPU/memory usage of node processes
ps aux | grep "modelcontextprotocol"

# 1. Minimal Configuration
- Only enable MCP servers you use regularly
- Each server consumes resources and context
- Review and remove unused servers monthly

# 2. Secure Secrets Management
- Never commit API keys to version control
- Use environment variables for all secrets
- Rotate credentials regularly
- Use read-only tokens when possible

# 3. Environment Separation
- Separate MCP servers for dev/staging/prod
- Use read-only connections for production queries
- Never enable write access to production via MCP

# 4. Documentation
- Document each MCP server's purpose
- Maintain team configuration template
- Update onboarding docs when adding servers

# 5. Testing
- Test MCP servers independently before adding to config
- Verify authentication before full integration
- Have fallback procedures if MCP unavailable

# 6. Monitoring
- Regularly check /mcp status
- Monitor MCP server logs for errors
- Track API usage to avoid rate limits

# 7. Version Control
- Track configuration template in git
- Document required environment variables
- Maintain changelog for configuration updates