# MCP Starter Kit

Two ready-to-use Model Context Protocol configs that give an AI agent a safe first
tool: read-only-ish access to a project folder via the official **filesystem** server.
One config works in almost every MCP client; the other is the VS Code variant.

Companion to the *Models & Local LLMs* and *Beyond Copilot* topics of the course.

---

## Which file do I use?

| File | Use it in | Root key |
|------|-----------|----------|
| `mcp.json` | Cursor, Claude Code, Claude Desktop, Cline, Continue, Windsurf, and most other clients | `mcpServers` |
| `mcp.vscode.json` | **VS Code** (Copilot Chat) | `servers` ⚠ |

> **The #1 gotcha:** VS Code uses **`servers`** as the root key, not `mcpServers`.
> Same structure, different name. Copy a Claude Desktop / Cursor config into VS Code
> unchanged and it will *silently fail*. That's the only difference between the two files here.

---

## Where to put it (per tool)

| Tool | Location |
|------|----------|
| **Cursor** | `.cursor/mcp.json` in the project root (or `~/.cursor/mcp.json` for global). Picks up changes automatically. |
| **VS Code** | `.vscode/mcp.json` in the workspace, or run `MCP: Open User Configuration` from the Command Palette. |
| **Claude Code** | Run `claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .`, or drop a `.mcp.json` at the repo root. |
| **Claude Desktop** | Settings → Developer → Edit Config → `claude_desktop_config.json`. |
| **Cline** | Click the MCP Servers icon in the Cline panel → Configure → `cline_mcp_settings.json`. |
| **Continue** | `~/.continue/config.json` (Continue uses an `mcpServers` array). |

The `filesystem` server only allows the directories you pass as arguments. `"."` means
"the folder the client launches it from." Replace it with an absolute path, or add more
paths, to widen or narrow access:

```json
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects", "/Users/you/docs"]
```

---

## Adding a remote (HTTP) server

Local stdio servers use `command` + `args`. Remote servers use a `url` instead. Example
using GitHub's **official** remote MCP server (the old `@modelcontextprotocol/server-github`
npm package is no longer maintained):

```json
{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}
```

In VS Code, the same entry goes under `"servers"` and supports `"type": "http"`.

---

## Verify it connected

- **VS Code / Copilot:** open Copilot Chat, type `#`, and look for the server's tools in the list.
- **Claude Code:** run `claude mcp list` in the terminal.
- **Cursor:** Settings → MCP — look for a green status dot.
- **Claude Desktop:** start a new chat and ask "what tools do you have?"

Then try: *"List the files in this folder and summarize what this project does."*
Watch the agent reason → call the filesystem tool → observe → answer.

---

## Security notes

- **Least privilege.** Only grant the directories an agent actually needs. Don't point the
  filesystem server at your home directory or anything with secrets.
- **Never hardcode tokens** in a committed config. Use environment-variable references
  (e.g. VS Code supports `${env:VAR_NAME}`) or your client's secret handling.
- **Approve consequential tool calls.** Keep confirmation prompts on for servers that can
  write or take external actions; auto-approve only servers you fully trust.
- Treat anything a server returns as **untrusted data, not commands** — the prompt-injection
  caveat from the MCP topic applies.

Find more servers in the MCP registry and the `awesome-mcp-servers` lists.