# MCP Servers

MCP (Model Context Protocol) is an open standard by Anthropic that allows Claude Code to connect to external tools, databases, APIs, and services. With MCP, you can significantly extend Claude Code's capabilities.

## What is MCP?

### Core Concepts

MCP is an **open protocol** that defines communication standards between AI assistants and external systems. It consists of three core components:

| Component | Description | Examples |
|-----------|-------------|----------|
| **Tools** | Executable actions | Query databases, send requests, manipulate files |
| **Resources** | Readable data | File contents, API responses, database records |
| **Prompts** | Predefined task templates | Code review templates, report generation templates |

### Why MCP?

- **Extended capabilities**: Let Claude access systems it couldn't otherwise reach

- **Real-time data**: Get the latest documentation, database content, API data

- **Automation**: Execute deployments, send notifications, manage resources

- **Privacy**: Data processed locally, no need to upload to the cloud

## Quick Start

### Check MCP Status

```
> /mcp
```

Shows the status of currently configured MCP servers.

### Add MCP Server

Use the `claude mcp add` command:

```bash
# Add filesystem server
claude mcp add filesystem npx -y @modelcontextprotocol/server-filesystem /path/to/directory

# Add SQLite database server
claude mcp add sqlite npx -y mcp-server-sqlite ./database.db

# Add custom server
claude mcp add my-server node /path/to/server.js
```

### Configuration File

You can also create a `.mcp.json` file in your project root:

```json
{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"]
  },
  "database": {
    "command": "npx",
    "args": ["-y", "mcp-server-sqlite", "./data.db"]
  }
}
```

## Popular MCP Servers

### Filesystem

Access local filesystem:

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

**Features**: Read, write, and search files in the specified directory.

### SQLite Database

Connect to SQLite database:

```json
{
  "sqlite": {
    "command": "npx",
    "args": ["-y", "mcp-server-sqlite", "./database.db"]
  }
}
```

**Features**: Execute SQL queries, manage database schema.

### GitHub

Connect to GitHub repositories:

```json
{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_TOKEN": "${GITHUB_TOKEN}"
    }
  }
}
```

**Features**: Manage Issues, PRs, repository operations.

### Context7 (Documentation Retrieval)

Get the latest library documentation:

```json
{
  "context7": {
    "command": "npx",
    "args": ["-y", "@context7/mcp-server"]
  }
}
```

**Features**: Retrieve up-to-date documentation and code examples for any library.

### Supabase

Connect to Supabase backend:

```json
{
  "supabase": {
    "command": "npx",
    "args": ["-y", "@supabase/mcp-server"],
    "env": {
      "SUPABASE_URL": "${SUPABASE_URL}",
      "SUPABASE_KEY": "${SUPABASE_KEY}"
    }
  }
}
```

**Features**: Database operations, authentication, storage management.

### Docker

Container management:

```json
{
  "docker": {
    "command": "npx",
    "args": ["-y", "@docker/mcp-server"]
  }
}
```

**Features**: Manage containers, images, networks.

## Server Types

### stdio (Local Process)

The most common type, runs as a local subprocess:

```json
{
  "my-server": {
    "command": "node",
    "args": ["./server.js"],
    "env": {
      "API_KEY": "${API_KEY}"
    }
  }
}
```

**Characteristics**:

- Runs locally, data stays on your machine

- Claude Code manages process lifecycle

- Ideal for filesystem, local databases

### SSE (Server-Sent Events)

> **⚠️ As of MCP spec 2025-11-25, SSE is deprecated.** New connections should use **Streamable HTTP** (see HTTP section below). SSE is retained only for backward compatibility with existing servers.


Connect to remote hosted MCP servers:

```json
{
  "remote-server": {
    "type": "sse",
    "url": "https://mcp.example.com/sse"
  }
}
```

**Characteristics**:

- Suitable for cloud services

- Supports OAuth authentication

- No local installation required

### HTTP

RESTful API approach:

```json
{
  "api-server": {
    "type": "http",
    "url": "https://api.example.com/mcp",
    "headers": {
      "Authorization": "Bearer ${API_TOKEN}"
    }
  }
}
```

## Environment Variables

MCP configuration supports environment variable substitution:

```json
{
  "my-server": {
    "command": "node",
    "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
    "env": {
      "DATABASE_URL": "${DATABASE_URL}",
      "API_KEY": "${API_KEY}",
      "DEFAULT_NAMESPACE": "${K8S_NAMESPACE:-default}"
    }
  }
}
```

**Syntax**:

- `${VAR}` - Substitute with environment variable value

- `${VAR:-default}` - Use default value if variable is not set

## Practical Examples

### Example 1: Database Query Assistant

```json
{
  "postgres": {
    "command": "npx",
    "args": ["-y", "mcp-server-postgres"],
    "env": {
      "DATABASE_URL": "postgresql://user:pass@localhost/mydb"
    }
  }
}
```

Usage:

```
> Query total order amount for the last 7 days
> Find the top 10 users with the most purchases
```

### Example 2: Kubernetes Operations

```json
{
  "kubernetes": {
    "command": "node",
    "args": ["./k8s-mcp-server.js"],
    "env": {
      "KUBECONFIG": "${KUBECONFIG}",
      "K8S_NAMESPACE": "${K8S_NAMESPACE:-default}"
    }
  }
}
```

Usage:

```
> List the status of all Pods
> Restart the api-server deployment
> Show recent error logs
```

### Example 3: Multi-Server Configuration

```json
{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "./src"]
  },
  "database": {
    "command": "npx",
    "args": ["-y", "mcp-server-sqlite", "./data.db"]
  },
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_TOKEN": "${GITHUB_TOKEN}"
    }
  }
}
```

## Troubleshooting

### Server Won't Start

1. Check if the command is properly installed:
   ```bash
   npx -y @modelcontextprotocol/server-filesystem --help
   ```

2. Check if environment variables are set:
   ```bash
   echo $GITHUB_TOKEN
   ```

3. Check Claude Code logs for error messages

### Tools Not Available

1. Use `/mcp` to check server status

2. Verify configuration file format (JSON syntax)

3. Restart Claude Code to reload configuration

### Permission Issues

- Ensure file paths have read/write permissions

- Database connection string is correct

- API Token is valid and has sufficient permissions

## Security Recommendations

1. **Principle of least privilege**: Only grant necessary access

2. **Protect sensitive info**: Use environment variables for tokens and passwords

3. **Limit path access**: Only expose necessary directories for filesystem servers

4. **Rotate keys regularly**: Periodically update API tokens

## Security Notes

An MCP server runs with your identity — it can read data, invoke tools, and reach credentials. Adding a third-party MCP server is effectively wiring external code into your development environment, so treat it with care.

**Main risks**

- **Data exfiltration**: A malicious or compromised server can send your code, files, or conversation content to an external destination.

- **Tool poisoning**: A server embeds hidden instructions inside its tool descriptions, nudging Claude into actions you never authorized.

- **Credential exposure**: A misconfigured server may read environment variables, secrets, or tokens.

- **Over-broad power**: Granting tool capabilities beyond what's actually needed widens the attack surface.

**Key mitigations**

- **Install only trusted servers**: Prefer official, reviewed, or open-source auditable MCP servers; avoid implementations of unknown origin.

- **Least privilege**: Review each server's declared tool scopes one by one and expose only the capabilities and directories you truly need.

- **Keep human approval gates**: Claude Code asks before running a tool call — don't blindly approve or fully auto-approve destructive, write, or credential-touching operations.

- **Isolate credentials**: When running commands in a sandbox, use `sandbox.credentials` to block sandboxed processes from reading secrets and environment variables.

- **Audit calls**: Log and periodically review tool-call activity to catch anomalous behavior early.

For the full threat model, sandboxing, and credential-isolation configuration, see [Security Best Practices](/docs/advanced/security).

## Next Steps

- Learn about the [Plugin System](/docs/advanced/plugins) to create custom functionality

- Check [CLI Tips](/docs/usage/cli-tips) to boost efficiency

- Explore [Workflow Tips](/docs/usage/workflow-tips) to optimize development flow