# MCP Setup

Configure and connect MCP servers to Claude Code with OAuth authentication, tool access, and remote server support for seamless external integrations

---


## Metadata

**Title:** MCP Setup
**Category:** commands
**Author:** JSONbored
**Added:** October 2025
**Tags:** mcp, integration, oauth, remote-server, tools, setup
**URL:** https://claudepro.directory/commands/mcp-setup

## Overview

Configure and connect MCP servers to Claude Code with OAuth authentication, tool access, and remote server support for seamless external integrations

## Content

The /mcp-setup command guides you through configuring Model Context Protocol (MCP) servers in Claude Code, enabling seamless integration with external tools, databases, and APIs through Anthropic's open-source standard.
FEATURES
• Remote MCP Server Support: Connect to cloud-hosted MCP servers with native OAuth authentication
• Local Server Configuration: Set up containerized MCP servers using Docker MCP Toolkit
• Project-Scoped Setup: Configure .mcp.json for team-wide server access
• User-Global Setup: Install personal MCP servers available across all projects
• OAuth Management: One-click authentication with secure credential storage
• Tool Discovery: Automatically detect and enable available tools from connected servers
• Resource Access: Grant Claude Code access to databases, file systems, and APIs
• Health Monitoring: Verify server connectivity and troubleshoot connection issues
USAGE

 /mcp-setup [server-type] [options]

Server Types
• --remote - Configure remote MCP server with OAuth (default)
• --local - Set up local/Docker MCP server
• --list - List all available MCP servers from marketplace
• --status - Check status of configured servers
Configuration Scope
• --project - Add to .mcp.json (team-shared, checked into git)
• --user - Add to ~/.config/claude/mcp.json (personal)
Popular Servers
• --github - GitHub REST API integration
• --linear - Linear issue tracking
• --sentry - Error monitoring integration
• --postgres - PostgreSQL database access
• --mongodb - MongoDB database integration
• --slack - Slack messaging integration
• --google-drive - Google Drive file access
• --aws - AWS service integration
EXAMPLES
Remote GitHub MCP Server with OAuth
Command:

 /mcp-setup --remote --github --project

What happens:
1) Claude detects project needs GitHub integration
2) Generates .mcp.json configuration:

 {
 "mcpServers": {
 "github": {
 "type": "remote",
 "url": "https://mcp.github.com",
 "auth": {
 "type": "oauth",
 "provider": "github"
 },
 "tools": [
 "create_pull_request",
 "get_repository",
 "list_issues",
 "create_issue",
 "update_issue",
 "merge_pull_request"
 ],
 "resources": [
 "repository://repos",
 "issue://issues",
 "pull_request://pulls"
 ]
 }
 }
 }

3) Prompts OAuth flow:
 • Opens browser for GitHub authentication
 • Requests necessary scopes (repo, issues, pull_requests)
 • Stores OAuth token securely in system keychain
4) Verifies connection:
 • Tests API connectivity
 • Lists available repositories
 • Confirms tool access
Usage in Claude Code:

 # Claude can now use GitHub tools automatically
 User: "Create a PR for my authentication refactor"
 Claude: *uses create_pull_request tool from GitHub MCP server*
 User: "What issues are assigned to me?"
 Claude: *uses list_issues tool to fetch assigned issues*

Local Postgres MCP Server with Docker
Command:

 /mcp-setup --local --postgres --project

Generated Configuration:

 {
 "mcpServers": {
 "postgres": {
 "type": "stdio",
 "command": "docker",
 "args": [
 "run",
 "-i",
 "--rm",
 "--network=host",
 "mcp/postgres"
 ],
 "env": {
 "POSTGRES_CONNECTION_STRING": "postgresql://localhost:/mydb"
 },
 "tools": [
 "execute_query",
 "list_tables",
 "describe_table",
 "get_schema"
 ]
 }
 }
 }

Environment Setup:

 # Claude creates .env.local for secrets
 POSTGRES_CONNECTION_STRING=postgresql://user:password@localhost:/mydb

Usage:

 User: "What tables are in the database?"
 Claude: *uses list_tables tool*
 User: "Show me all users created in the last week"
 Claude: *uses execute_query tool with date filtering*

Multiple MCP Servers for Full-Stack Project
Command:

 /mcp-setup --project --github --linear --sentry --postgres

Generated .mcp.json:

 {
 "mcpServers": {
 "github": {
 "type": "remote",
 "url": "https://mcp.github.com",
 "auth": { "type": "oauth", "provider": "github" }
 },
 "linear": {
 "type": "remote",
 "url": "https://mcp.linear.app",
 "auth": { "type": "oauth", "provider": "linear" }
 },
 "sentry": {
 "type": "remote",
 "url": "https://mcp.sentry.io",
 "auth": {
 "type": "bearer",
 "token": "${SENTRY_AUTH_TOKEN}"
 }
 },
 "postgres": {
 "type": "stdio",
 "command": "docker",
 "args": ["run", "-i", "--rm", "mcp/postgres"],
 "env": {
 "POSTGRES_CONNECTION_STRING": "${POSTGRES_CONNECTION_STRING}"
 }
 }
 }
 }

Workflow Integration:

 User: "Check Sentry for errors related to authentication, create Linear tickets for each unique error, and analyze the auth database table"
 Claude:
 1. *Uses Sentry MCP to fetch recent auth errors*
 2. *Groups by error type and stack trace*
 3. *Uses Linear MCP to create tickets with error details*
 4. *Uses Postgres MCP to query auth table for affected users*
 5. Presents comprehensive report with tickets created

User-Global MCP Servers (Personal Setup)
Command:

 /mcp-setup --user --slack --google-drive

Configuration Location:

 ~/.config/claude/mcp.json

Benefit:
• Available across ALL projects
• Personal authentication (not shared with team)
• Useful for productivity tools
MCP SERVER MARKETPLACE
Development Tools
• GitHub - Repository management, PRs, issues, CI/CD
• GitLab - GitLab API integration
• Bitbucket - Bitbucket Cloud/Server integration
Issue Tracking
• Linear - Issue tracking and project management
• Jira - Atlassian Jira integration
• Asana - Task management
Monitoring & Observability
• Sentry - Error tracking and monitoring
• Datadog - Infrastructure monitoring
• New Relic - Application performance monitoring
Databases
• PostgreSQL - PostgreSQL database access
• MongoDB - MongoDB document database
• MySQL - MySQL/MariaDB integration
• Redis - Redis cache and data structure store
• Supabase - Supabase backend platform
Cloud Platforms
• AWS - Amazon Web Services integration
• Google Cloud - GCP service integration
• Azure - Microsoft Azure integration
• Vercel - Vercel deployment platform
• Cloudflare - Cloudflare edge platform
Communication
• Slack - Slack messaging and notifications
• Discord - Discord server integration
• Notion - Notion workspace access
AI & ML
• Pinecone - Vector database for embeddings
• Weaviate - Vector search engine
• Chroma - Embedding database
AUTHENTICATION METHODS
OAuth 2.0 (Recommended for Remote Servers)

 {
 "auth": {
 "type": "oauth",
 "provider": "github",
 "scopes": ["repo", "issues"]
 }
 }

Benefits:
• No API keys to manage
• Automatic token refresh
• Secure credential storage
• One-click authentication
Bearer Token

 {
 "auth": {
 "type": "bearer",
 "token": "${API_TOKEN}"
 }
 }

Use When:
• Service doesn't support OAuth
• Using API keys or personal access tokens
• Environment variables preferred
No Authentication (Local/Docker)

 {
 "type": "stdio",
 "command": "docker",
 "args": ["run", "-i", "--rm", "mcp/server"]
 }

Use When:
• Local development servers
• Containerized services
• Internal network resources
DOCKER MCP TOOLKIT
Installing MCP Toolkit

 # Claude runs this automatically
 docker pull mcp/toolkit

Available Containerized Servers (+)
• Pre-built, security-audited containers
• One-command installation
• Isolated environments
• Automatic updates
Example: Setup Multiple Servers via Docker

 /mcp-setup --local --postgres --redis --mongodb

Generated docker-compose.yml:

 version: '3.8'
 services:
 mcp-postgres:
 image: mcp/postgres
 environment:
 - POSTGRES_CONNECTION_STRING=${POSTGRES_CONNECTION_STRING}
 network_mode: host
 mcp-redis:
 image: mcp/redis
 environment:
 - REDIS_URL=${REDIS_URL}
 network_mode: host
 mcp-mongodb:
 image: mcp/mongodb
 environment:
 - MONGODB_URI=${MONGODB_URI}
 network_mode: host

HEALTH MONITORING & TROUBLESHOOTING
Check Server Status

 /mcp-setup --status

Output:

 ✓ github (remote) - Connected, 6 tools available
 ✓ linear (remote) - Connected, 8 tools available
 ✗ postgres (local) - Connection failed: Docker container not running
 ⚠ sentry (remote) - Connected, rate limit: 80% used

Test Server Connection

 /mcp-setup --test github

Verification Steps:
1) Ping server endpoint
2) Verify authentication
3) List available tools
4) Test tool invocation
5) Check resource access
SECURITY BEST PRACTICES
Project vs User Configuration
Project (.mcp.json - checked into git):

 {
 "mcpServers": {
 "github": {
 "type": "remote",
 "url": "https://mcp.github.com",
 "auth": {
 "type": "oauth",
 "provider": "github"
 }
 }
 }
 }

• ✅ Server configuration (URLs, tool lists)
• ✅ Authentication method (oauth, bearer)
• ❌ NO secrets or tokens
User (~/.config/claude/mcp.json - personal):
• ✅ OAuth tokens (stored in system keychain)
• ✅ Personal API keys
• ✅ User-specific servers
Environment Variables for Secrets

 # .env.local (NOT checked into git)
 SENTRY_AUTH_TOKEN=abc123...
 POSTGRES_CONNECTION_STRING=postgresql://...
 AWS_ACCESS_KEY_ID=AKIA...
 AWS_SECRET_ACCESS_KEY=...

Reference in .mcp.json:

 {
 "auth": {
 "type": "bearer",
 "token": "${SENTRY_AUTH_TOKEN}"
 }
 }

ADVANCED CONFIGURATION
Tool Permissions (Restrict Access)

 {
 "mcpServers": {
 "github": {
 "tools": ["get_repository", "list_issues"],
 "excludeTools": ["delete_repository", "force_push"]
 }
 }
 }

Resource Filtering

 {
 "mcpServers": {
 "postgres": {
 "resources": ["table://users", "table://posts"],
 "excludeResources": ["table://internal_*"]
 }
 }
 }

Rate Limiting

 {
 "mcpServers": {
 "github": {
 "rateLimit": {
 "requests": ,
 "period": "hour"
 }
 }
 }
 }

MIGRATION FROM MANUAL SETUP
Before (Manual Configuration)

 // Scattered across multiple config files
 // Manual OAuth flow
 // No centralized management

After (/mcp-setup)

 /mcp-setup --project --github --linear --sentry
 # One command, automatic OAuth, team-ready config

TEAM COLLABORATION
Shared Project Setup
1) Lead developer runs /mcp-setup --project --github --linear
2) Commits .mcp.json to git
3) Team members clone repo
4) Each member authenticates with OAuth (personal credentials)
5) Everyone has same tool access
Onboarding New Developers

 # New team member clones repo
 git clone repo.git
 cd repo
 # Claude Code detects .mcp.json
 Claude: "I found 3 MCP servers configured. Would you like to authenticate?"
 User: "yes"
 Claude: *opens OAuth flows for GitHub, Linear, Sentry*
 # Done - fully integrated in 30 seconds

BEST PRACTICES
1) Use Project Scope for Team Tools: GitHub, Linear, CI/CD
2) Use User Scope for Personal Tools: Slack, Google Drive, Notion
3) Prefer OAuth Over API Keys: Better security, auto-refresh
4) Docker for Local Services: Isolated, reproducible environments
5) Monitor Rate Limits: Check --status regularly
6) Test After Setup: Use --test to verify connectivity
7) Document Custom Servers: Add comments in .mcp.json
8) Version Control Config: Commit .mcp.json, ignore .env.local
INSTALLATION
CLAUDE CODE:
1) Create commands directory: mkdir -p .claude/commands
2) Create command file: touch .claude/commands/mcp-setup.md
3) Add command content from the Command Content section above to .claude/commands/mcp-setup.md
4) Command is now available as /mcp-setup in Claude Code
5) Optional: Create personal version in ~/.claude/commands/mcp-setup.md for global access
Requirements:
? Claude Code CLI installed
? Project directory initialized (for project commands)
CONFIGURATION
Temperature: 0.3
Max Tokens: 
System Prompt:
You are an MCP (Model Context Protocol) integration expert specializing in configuring Claude Code to connect with external tools, databases, and APIs through remote and local MCP servers with OAuth authentication
TROUBLESHOOTING
1) OAuth flow fails with 'redirect_uri mismatch' error during MCP server authentication
 Solution: Verify Claude Code version + supports remote MCP OAuth. Check server configuration uses correct callback URL: http://localhost:/oauth/callback. Restart Claude Code after updating .mcp.json to refresh OAuth handlers.
2) MCP server shows 'Connected' but tools are not available to Claude during conversation
 Solution: Run /mcp-setup --status to verify tools list. Check .mcp.json 'tools' array includes desired tool names. Some servers require explicit tool enabling - add 'tools': ['*'] to enable all. Restart Claude Code session to refresh tool registry.
3) Docker MCP server fails with 'container not found' despite successful setup command
 Solution: Verify Docker daemon is running: docker ps. Check container image pulled: docker images | grep mcp. Use --network=host flag in args array. For Apple Silicon, add 'platform': 'linux/amd64' to server config.
4) Environment variable substitution fails with 'token is undefined' in bearer auth
 Solution: Ensure .env.local exists in project root with variable defined. Claude Code loads env vars from .env.local, .env, or shell environment. Use ${VAR_NAME} syntax in .mcp.json. Restart Claude Code to reload environment variables after changes.
5) Rate limit errors when using GitHub MCP server with 'API rate limit exceeded' message
 Solution: Check rate limit status: /mcp-setup --status. OAuth tokens have higher rate limits than API keys - switch to OAuth auth type. Add 'rateLimit' config to slow Claude's request frequency. Cache frequently accessed resources in CLAUDE.md to reduce API calls.
TECHNICAL DETAILS
Documentation: https://docs.claude.com/en/docs/claude-code/mcp


---

Source: Claude Pro Directory
Website: https://claudepro.directory
URL: https://claudepro.directory/commands/mcp-setup

This content is optimized for Large Language Models (LLMs).
For full formatting and interactive features, visit the website.