# MCP Context & Practical Guide

---

## 1. The Universal Translator for AI: Understanding the Model Context Protocol (MCP)

The **Model Context Protocol (MCP)** is an open standard that acts like a "USB-C port for AI," creating a universal, secure bridge between AI systems and external data sources, tools, and services.  
Instead of writing one-off integrations for every API, developers expose a **single MCP server** and any MCP-compliant AI client can "plug in."

**Architecture in a nutshell**

```txt
┌──────────────┐        JSON-RPC (stdio or SSE)        ┌───────────────┐
│  MCP Client  │  <──────────────────────────────────► │  MCP Server   │
│   (the AI)   │                                       │  (your tools) │
└──────────────┘                                       └───────────────┘
```

* A **client** (Claude Code, Claude Desktop, Cursor, etc.) asks for data/actions.  
* A **server** exposes tools & context in the MCP JSON-RPC schema.  
* The protocol is model-agnostic, fostering an open "plug-and-play" ecosystem.

---

## 2. 🚀 FastMCP – Accelerating MCP Development

**FastMCP** is a Pythonic framework that removes most boilerplate from MCP servers.

| Feature | What it gives you |
|---------|-------------------|
| `@mcp.tool` decorator | Turn any Python function into an MCP tool in two lines |
| Python-native types | Automatic JSON-Schema generation for parameters |
| Official SDK | FastMCP 1.0 merged into the MCP Python SDK |
| Full toolkit | FastMCP 2.0 adds a rich client, test harness, CLI, etc. |

---

## 3. 🖱️ Cursor – An AI Code Editor at the Forefront of MCP Innovation

Cursor demonstrates how deeply MCP can super-charge an AI product:

1. **One-click installer & OAuth** – add new servers without leaving the editor.  
2. **Agent "super-powers"** – search/replace across huge codebases, run linters, etc. via MCP tools.  
3. **Images in context** – send screenshots/diagrams to the AI through MCP.  
4. **Growing Marketplace** – a curated directory of ready-made MCP servers for everything from GitHub to AWS.

---

## 4. Hands-On Guide — Creating & Adding MCP Servers to Claude Code

The rest of this document is a **step-by-step, copy-paste-ready handbook** for engineers who want to:

* build or obtain an MCP server  
* register it in **Claude Code** (CLI tool)  
* share it with teammates safely

### 4.1 Server Delivery Formats & How to Register

| Delivery format | Transport | What you install | Launch command (`claude mcp add … -- …`) |
|-----------------|-----------|------------------|------------------------------------------|
| **NPM package** | stdio | Node ≥ 18 + package from npm | `npx -y <pkg> …` |
| **Local binary / Python script** | stdio | Executable on `$PATH` or `pip` module | `/usr/local/bin/server …` or `python -m my_server …` |
| **Docker image** | stdio | Docker Desktop | `docker run --rm -i <image> …` |
| **Hosted endpoint (SSE)** | SSE | nothing | (URL after `--transport sse`) |

> MCP itself supports only two transports (stdio & SSE).  
> The table shows common *packaging* strategies for stdio servers.

---

### 4.2 Adding a Server – Command Patterns

Basic syntax:

```bash
# stdio server
claude mcp add <name> [options] -- <command> [args...]

# SSE server
claude mcp add --transport sse <name> <url>
```

Common flags:

* `-s {local|project|user}` Scope (default *local*)  
* `-e KEY=VALUE`      Env vars for secrets  
* `--timeout 15000`    Startup timeout (ms)  
* `--`           Separates Claude args from server command

---

### 4.3 Understanding Claude Code MCP Server Scopes

Claude Code offers three distinct scope levels for MCP server configuration, each with specific use cases and storage locations:

#### Scope Hierarchy and Precedence

When servers with the same name exist at multiple scopes, Claude Code resolves conflicts by prioritizing:
1. **Local** (highest priority)
2. **Project** 
3. **User** (lowest priority)

This allows personal configurations to override shared ones when needed.

#### Local Scope (Default)

* **Purpose**: Personal development servers, experimental configurations, or sensitive credentials for current project only
* **Storage**: Project-specific user settings (private to you)
* **Visibility**: Only accessible when working within the current project directory
* **Use case**: Testing new servers, personal API keys, project-specific tools

```bash
# Add a local-scoped server (default)
claude mcp add my-private-server -- /path/to/server

# Explicitly specify local scope
claude mcp add my-private-server -s local -- /path/to/server
```

#### Project Scope

* **Purpose**: Team collaboration and shared tools
* **Storage**: `.mcp.json` file in project root (can be version controlled)
* **Visibility**: Available to all team members who have the repository
* **Use case**: Project-specific tools, shared development servers, team resources

```bash
# Add a project-scoped server
claude mcp add shared-server -s project -- /path/to/server
```

The resulting `.mcp.json` file structure:
```json
{
  "mcpServers": {
    "shared-server": {
      "command": "/path/to/server",
      "args": [],
      "env": {}
    }
  }
}
```

**Security Note**: Claude Code prompts for approval before using project-scoped servers. Reset approvals with: `claude mcp reset-project-choices`

#### User Scope

* **Purpose**: Personal utilities available across all projects
* **Storage**: Global user configuration
* **Visibility**: Available in all projects on your machine
* **Use case**: Personal development tools, frequently-used services, cross-project utilities

```bash
# Add a user-scoped server
claude mcp add my-utility -s user -- /path/to/server
```

---

### 4.4 Example Configurations

#### 4.4.1 Example A – NPM Server with Environment Variables

```bash
# Load environment variables and add server
set -a; source .env; set +a

claude mcp add exchange-server -s user \
  -e AZURE_AD_CLIENT_ID=$AZURE_AD_CLIENT_ID \
  -e AZURE_AD_TENANT_ID=$AZURE_AD_TENANT_ID \
  -- npx -y msexchange-mcp
```

#### 4.4.2 Example B – Local Python Script

```bash
pip install mypython-mcp

claude mcp add pytools -s project \
  -- python -m mypython_mcp --mode safe
```

#### 4.4.3 Example C – Docker-Wrapped Server

```bash
docker pull ghcr.io/acme/awesome-mcp:1.4.0

claude mcp add awesome -s project \
  -- docker run --rm -i -e OPENAI_API_KEY ghcr.io/acme/awesome-mcp:1.4.0
```

#### 4.4.4 Example D – Remote SSE Endpoint

```bash
claude mcp add --transport sse reports -s project \
  https://mcp.example.com/sse?token=XYZ123
```

---

### 4.5 Managing Servers

```bash
claude mcp list          # all servers & launch commands
claude mcp get exa       # details of one
claude mcp remove exa    # delete from given scope
/mcp                     # in Claude chat: live health check
```

### 4.6 Additional Management Commands

```bash
# Import servers from Claude Desktop (macOS/WSL only)
claude mcp add-from-claude-desktop

# Add server from JSON configuration
claude mcp add-json weather-api '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"]}'

# Use Claude Code as an MCP server for other clients
claude mcp serve
```

---

## 5. Team-Ready Best Practices

1. **Choose packaging once** – npm for JS, pip/binary for Python/Go, Docker for everything else.  
2. **Pin versions** – e.g. `msexchange-mcp@1.0.1`, `ghcr.io/…:1.4.0` to avoid breaking changes.  
3. **Never commit secrets** – use env vars, `.env` files (gitignored), or vault/OAuth.  
4. **Scope selection**:
   - Use `local` for personal experiments and sensitive credentials
   - Use `project` for team-shared tools (creates `.mcp.json` for version control)
   - Use `user` for personal utilities you want everywhere
5. **Environment variables** – Pass credentials with `-e` flags, not hardcoded in commands
6. **CI smoke test** – `MCP_TIMEOUT=10000 claude mcp list` in CI to ensure servers spin up.  
7. **Prompt-injection awareness** – especially for internet-facing tools; validate inputs.

---

## 6. Troubleshooting Cheat-Sheet

| Symptom | Root cause | Action |
|---------|------------|--------|
| `missing required argument 'commandOrUrl'` | Forgot the command portion after `--` | Re-run with full syntax |
| Start-up hangs >10 s | Heavy Docker image / network lag | `MCP_TIMEOUT=30000` or optimize server |
| "Exec format error" | Wrong binary arch | Use multi-arch image or rebuild |
| SSE server appears offline | URL/firewall problem | `curl -N <url>` to debug |
| Server not in `claude mcp list` | Wrong scope or caching issue | Check scope with `claude mcp get <name>` |
| "Connection closed" error | Server can't find config files | Ensure `.env` or config files are in working directory |
| Node.js syntax errors | Version incompatibility | Check Node.js version compatibility |

---

## 7. Claude Code vs Claude Desktop: Key Differences

| Feature | Claude Code | Claude Desktop |
|---------|-------------|----------------|
| Configuration format | CLI commands (`claude mcp add`) | JSON file (`claude_desktop_config.json`) |
| Scope management | Three scopes (local/project/user) | Single global configuration |
| Team sharing | Project scope via `.mcp.json` | Manual config sharing |
| Remote servers (SSE) | Supported | Limited support |
| Environment handling | Working directory aware | Fixed paths required |
| Configuration location | Multiple (based on scope) | Single JSON file |

---

## 8. Reference Links

1. Anthropic Docs – *Set up MCP for Claude Code*  
   <https://docs.anthropic.com/en/docs/claude-code/mcp>  
2. Anthropic – MCP Spec GitHub  
   <https://github.com/anthropics/claude-model-context-protocol>  
3. FastMCP GitHub  
   <https://github.com/fastmcp/fastmcp>  
4. Example MCP Servers:
   - Exa MCP Server (npm): <https://github.com/exa-labs/exa-mcp-server>
   - GitHub MCP Server: `@modelcontextprotocol/server-github`
   - SQLite MCP Server: `@modelcontextprotocol/server-sqlite`

---

With this consolidated overview **and** practical playbook, your team can move from "What is MCP?" to "We just wired a new tool into Claude in five minutes." Happy hacking!