Configuring Mcp Servers

MCP Server (Provider):

• Exposes capabilities through standardized interface
• Runs as separate process
• Communicates via transport protocol
• Provides prompts, resources, and/or tools

MCP Client (Consumer):

• Claude Code (or other AI applications)
• Connects to multiple servers
• Aggregates capabilities
• Routes requests to appropriate servers

Transport Types

1. Stdio (Standard Input/Output)

Use case: Local command-line tools and scripts

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": ["./build/index.js"],
      "env": {}
    }
  }
}

Characteristics:

• Simplest transport
• Process-to-process communication
• Local execution only
• No network overhead

Best for:

• Local file access
• Command-line utilities
• Development tools
• Simple integrations

2. SSE (Server-Sent Events)

Use case: HTTP-based streaming connections

{
  "mcpServers": {
    "remote-api": {
      "url": "https://api.example.com/mcp",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

Characteristics:

• HTTP streaming
• Server-to-client push
• Real-time updates
• Network-based

Best for:

• Remote services
• Real-time data feeds
• Cloud integrations
• Streaming responses

3. HTTP

Use case: RESTful API integrations

{
  "mcpServers": {
    "rest-api": {
      "url": "https://api.example.com/mcp",
      "transport": "http",
      "headers": {
        "X-API-Key": "${API_KEY}"
      }
    }
  }
}

Characteristics:

• Request-response pattern
• Standard HTTP methods
• Stateless
• Widely supported

Best for:

• REST APIs
• Third-party services
• Simple web services
• Standard integrations

Scope Levels

User-Level Configuration

Location: ~/.config/claude/mcp.json (macOS/Linux) or %APPDATA%\claude\mcp.json (Windows)

{
  "mcpServers": {
    "github": {
      "command": "uvx",
      "args": ["mcp-server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
      }
    },
    "google-calendar": {
      "command": "node",
      "args": ["./servers/calendar/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "xxx",
        "GOOGLE_CLIENT_SECRET": "xxx"
      }
    }
  }
}

Use when:

• Personal tool access (GitHub, Notion, Calendar)
• System-wide integrations
• User-specific credentials
• Global utilities

Project-Level Configuration

Location: .mcp/config.json (project root)

{
  "mcpServers": {
    "project-db": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "figma": {
      "command": "node",
      "args": ["./mcp/figma-server.js"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "${FIGMA_TOKEN}"
      }
    }
  }
}

Use when:

• Project-specific data sources
• Team-shared configurations
• Development database access
• Project tool integrations

Server Capabilities

Prompts

Purpose: Reusable prompt templates and workflows

// MCP Server exposes prompts
{
  prompts: [
    {
      name: "code-review",
      description: "Comprehensive code review workflow",
      arguments: [
        { name: "file_path", required: true },
        { name: "focus_areas", required: false }
      ]
    }
  ]
}

Use cases:

• Standardized workflows
• Team conventions
• Complex multi-step processes
• Domain-specific templates

Resources

Purpose: Access to external data sources

// MCP Server exposes resources
{
  resources: [
    {
      uri: "file:///project/src/**/*.ts",
      name: "TypeScript Source Files",
      mimeType: "text/typescript"
    },
    {
      uri: "db://postgres/users",
      name: "User Database",
      mimeType: "application/json"
    }
  ]
}

Use cases:

• File system access
• Database connections
• API data sources
• Document repositories

Tools

Purpose: Callable functions and operations

// MCP Server exposes tools
{
  tools: [
    {
      name: "search_codebase",
      description: "Search across project files",
      parameters: {
        query: { type: "string", required: true },
        file_pattern: { type: "string", required: false }
      }
    }
  ]
}

Use cases:

• Custom operations
• External API calls
• Automated actions
• Service integrations

Configuration Examples

Filesystem Access

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"],
      "env": {}
    }
  }
}

Capabilities: Read/write local files, list directories, search content

GitHub Integration

{
  "mcpServers": {
    "github": {
      "command": "uvx",
      "args": ["mcp-server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Capabilities: Search repositories, read files, create issues, manage PRs

Slack Integration

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

Capabilities: Send messages, read channels, search conversations

Database Access

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/db"
      }
    }
  }
}

Capabilities: Query tables, analyze schema, execute SQL

Google Drive

{
  "mcpServers": {
    "gdrive": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-gdrive"],
      "env": {
        "GOOGLE_CLIENT_ID": "${GOOGLE_CLIENT_ID}",
        "GOOGLE_CLIENT_SECRET": "${GOOGLE_CLIENT_SECRET}"
      }
    }
  }
}

Capabilities: Read documents, search files, manage folders

Environment Variables

Secure Credential Management

Use environment variables for sensitive data:

{
  "mcpServers": {
    "api-service": {
      "command": "node",
      "args": ["./server.js"],
      "env": {
        "API_KEY": "${API_KEY}",
        "API_SECRET": "${API_SECRET}"
      }
    }
  }
}

Best practices:

1. Never hardcode credentials in config
2. Use ${VAR_NAME} syntax for substitution
3. Store secrets in .env file (gitignored)
4. Use system environment variables for user-level config
5. Document required environment variables

Environment File Example

.env (project root):

# MCP Server Credentials
GITHUB_TOKEN=ghp_xxxxxxxxxxxxx
SLACK_BOT_TOKEN=xoxb-xxxxxxxxxxxxx
DATABASE_URL=postgresql://localhost:5432/mydb
FIGMA_TOKEN=figd_xxxxxxxxxxxxx
API_KEY=xxxxxxxxxxxxx

Load in shell (before running Claude Code):

export $(cat .env | xargs)
claude

Creating Custom MCP Servers

Basic Server Structure

// my-mcp-server.ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

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

// Register tools
server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "custom_operation",
      description: "Performs custom operation",
      inputSchema: {
        type: "object",
        properties: {
          input: { type: "string" },
        },
      },
    },
  ],
}));

server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "custom_operation") {
    const result = performOperation(request.params.arguments.input);
    return { result };
  }
});

// Start server
const transport = new StdioServerTransport();
await server.connect(transport);

Register Custom Server

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["./my-mcp-server.js"],
      "env": {}
    }
  }
}

Popular MCP Servers

Official Servers

Community Servers

• Notion: Access Notion databases and pages
• Jira: Create/update issues, search projects
• Figma: Read designs, extract assets
• Shopify: Manage products, orders
• Stripe: Payment operations, customer management

Find more: https://github.com/modelcontextprotocol/servers

Best Practices

Configuration Organization

{
  "mcpServers": {
    // Group by category

    // Version Control
    "github": { "command": "uvx", "args": ["mcp-server-github"] },

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

    // Data Sources
    "postgres": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-postgres"] },
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem"] }
  }
}

Performance Optimization

1. Limit concurrent servers: Only load what you need
2. Use project scope: Don't load user-level servers for every project
3. Lazy loading: Start servers on-demand when possible
4. Cache responses: Implement caching in custom servers
5. Monitor resources: Track memory and CPU usage

Security Guidelines

1. Minimal permissions: Grant least privilege access
2. Validate inputs: Sanitize all tool parameters
3. Audit logging: Log all MCP operations
4. Rate limiting: Prevent abuse of external APIs
5. Credential rotation: Regularly update tokens and keys

Error Handling

// Custom server with proper error handling
server.setRequestHandler("tools/call", async (request) => {
  try {
    const result = await performOperation(request.params.arguments);
    return { result };
  } catch (error) {
    return {
      error: {
        code: "OPERATION_FAILED",
        message: error.message,
      },
    };
  }
});

Troubleshooting

Common Issues

Issue: Server not connecting

# Check server is installed
npx @modelcontextprotocol/server-filesystem --version

# Test server directly
echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | npx @modelcontextprotocol/server-filesystem /tmp

Issue: Environment variables not loading

// Verify variable is set
{
  "command": "sh",
  "args": ["-c", "echo $GITHUB_TOKEN && node server.js"]
}

Issue: Permission denied

# Check file permissions
chmod +x ./my-mcp-server.js

# Verify allowed directories
# Filesystem server only accesses specified paths

Debugging

Enable verbose logging:

{
  "mcpServers": {
    "debug-server": {
      "command": "node",
      "args": ["--inspect", "./server.js"],
      "env": {
        "DEBUG": "mcp:*"
      }
    }
  }
}

Advanced Topics

For detailed information on:

• MCP protocol specification → resources/mcp-architecture.md
• Popular MCP servers → resources/popular-servers.md
• Testing MCP connections → scripts/test-mcp-connection.js
• Configuration template → scripts/mcp-config-template.json

References

• MCP Specification: https://modelcontextprotocol.io/
• Official Servers: https://github.com/modelcontextprotocol/servers
• SDK Documentation: https://github.com/modelcontextprotocol/typescript-sdk
• Claude Code MCP: https://code.claude.com/docs/en/mcp