Skip to content

What Is MCP? A Practical Guide to the Model Context Protocol

beginner agents By AI Hub Team · updated

MCP (Model Context Protocol) is the open standard that connects AI apps to the systems around them: files, databases, tools. Anthropic open-sourced it in November 2024; OpenAI adopted it in March 2025 for the ChatGPT desktop app. As of October 2026 the spec version is 2026-07-28.

By the end of this guide a filesystem server is live in Claude Desktop: it reads, creates and searches files in two folders you choose, and every action needs your approval. The loop is small.

What MCP is

The official docs describe MCP as “a USB-C port for AI applications”: one connection standard, many devices. Under the hood it has three roles:

  • Client — the part of an app (Claude, ChatGPT, VS Code, Cursor) that talks to servers.
  • Server — a small program that exposes tools (actions the model can call), resources (data to reference) and prompts (templates).
  • Host — the app you actually use.

Messages are JSON-RPC 2.0. The key idea is discovery: a server hands the client its full tool list, so the model only sees tools that actually exist.

A short history

  • November 2024 — Anthropic open-sources MCP: spec, SDKs, Claude Desktop server support, and a reference repo for Google Drive, Slack, GitHub, Postgres and more.
  • March 2025 — OpenAI adopts MCP for the ChatGPT desktop app; Google DeepMind follows.
  • April 2025 — GitHub ships its official MCP server in public preview, rewritten in Go with Anthropic.

Transports: stdio vs Streamable HTTP

stdioStreamable HTTP
Runsserver as a local subprocessremote endpoint
WireJSON-RPC, one message per lineevery request is an HTTP POST to one endpoint
Responsenext line on stdouta JSON object or an SSE stream
Trustone shared trust domainprotocol auth flows (OAuth)
2026-07-28unchangedGET stream and sessions removed; stateless

Use stdio for everything local — that is what npx and uvx launch. Use Streamable HTTP for hosted servers.

What you need

  • Claude Desktop (macOS, Windows or Linux).
  • Node.js LTS — local servers launch through npx. Check with:
node --version

As of October 2026, TypeScript servers in the official repo require Node 24 or newer.

Step 1 — Check your Node.js version

Run node --version in a terminal. The official servers repo now wants Node 24 or newer for TypeScript servers, so anything older breaks. If the command is not found, install Node from nodejs.org and open a new terminal.

Step 2 — Add the filesystem server to claude_desktop_config.json

Find the config file:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

If it does not exist, create it. Exact example from the official docs, pointed at two folders:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\username\\Desktop",
        "C:\\Users\\username\\Downloads"
      ]
    }
  }
}

Replace the two paths with folders you actually want Claude to touch. The key "filesystem" is the name in the UI; -y skips the install prompt.

Step 3 — Restart the client and confirm the server appears

Quit Claude Desktop completely, tray icon included, and restart. Open the MCP section of settings — the docs call it the hammer icon. You should see “filesystem” listed.

If it is missing, run the exact command in a terminal:

npx -y @modelcontextprotocol/server-filesystem

A blank, silent terminal is a healthy stdio server.

Step 4 — Test a tool call and approve it

Ask Claude: “List the files on my Desktop.” The filesystem server exposes reads of files and directories, creation, move/rename, and search by name or content. An approval dialog appears before anything runs. Approve it. The list comes back.

Create a test file and search for it to cover the write path. If the approval dialog never appears, go back to Step 3.

Step 5 — Harden the setup: pin, scope, isolate

This is the part most guides skip. A local MCP server is an ordinary child process of your user account: it inherits your environment variables (tokens, API keys), can read anything your account can read, and can open outbound connections. The transport is not a sandbox.

Do these, in order:

  1. Prune. Delete servers you do not use; confirm you know where each remaining one comes from.
  2. Pin. npx and uvx pin only the top-level package; transitive dependencies re-resolve. For anything you do not trust fully, pin a container image by digest.
  3. Scope. Keep filesystem roots narrow, prefer read-only, never point a server at your home directory.
  4. Isolate. Baseline for an untrusted server: a container (Docker or Podman) with no volume mounts beyond what it needs; stdio works through a container.
  5. Secrets. Pass credentials through the per-server env block with narrowly scoped tokens.
  6. Prefer remote when offered. A hosted server over Streamable HTTP runs no code on your machine and uses the protocol’s auth flow instead of a local token.

Clients with one-click server installation must show the exact command before it runs (SEP-1024). Use that screen to read the package name twice.

What to expect

MomentWhat you should see
After restart“filesystem” appears in the MCP section of Claude Desktop
“List the files on my Desktop”Claude calls a directory tool; you approve; you get the list
“Create a file called test.txt”create tool; approval; the file exists in the folder you configured
“Find files containing ‘invoice’”search tool; approval; matching files

No numbers to quote. MCP is plumbing, not a benchmark. Success metric: the tool appears, the approval fires.

Security: what can go wrong

The protocol itself is honest; the attack surface is the code you launch. The official security guide names these patterns:

  • Malicious server. Typosquatting, lookalike repos, takeovers of abandoned projects. Check the exact package name against the official servers repo.
  • Tool poisoning and rug pulls. A server can embed instructions in its tool descriptions and swap definitions after you approved them. Prefer clients that pin definitions and re-prompt on changes.
  • Real incidents. The Cloud Security Alliance’s September 2025 review lists a cross-tenant leak at Asana (March 2025), a prompt-injection attack on the GitHub MCP server, an unauthenticated RCE in MCP Inspector, and the Sandworm_Mode typosquatting campaign (February 2026) against Claude Code, Cursor and Windsurf.

One line to remember: treat third-party local servers as untrusted code with exactly the privileges you hand it — and hand it as few as possible.

Troubleshooting

Server not showing up / no hammer icon. Restart the client, check the JSON for syntax errors (a trailing comma breaks parsing), use absolute paths, and run the command in a terminal. Logs live in %APPDATA%\Claude\logs (Windows) and ~/Library/Logs/Claude (macOS): mcp.log for the client side, mcp-server-SERVERNAME.log for the server’s stderr.

ENOENT with ${APPDATA} in the config. The client does not expand environment variables in Windows paths. Expand the value yourself and pass it through the env block:

"env": { "APPDATA": "C:\\Users\\you\\AppData\\Roaming" }

“npm should be installed globally”. Run npm install -g npm, then check that %APPDATA%\npm exists.

Tool calls fail silently. Open mcp-server-SERVERNAME.log. The server’s stderr explains almost everything.

FAQ

Does MCP work with ChatGPT, or only Claude? Both. OpenAI adopted MCP in March 2025 for the ChatGPT desktop app. As of October 2026, named supporters include Claude, ChatGPT, VS Code, Cursor and MCPJam.

Can an MCP server read my files without asking? A local server can do anything your account can do — but clients gate tool calls behind approval dialogs, and you control which folders a server is pointed at.

What is the difference between stdio and Streamable HTTP? stdio is local: the client launches the server and talks over stdin/stdout. Streamable HTTP is remote: one endpoint, every request a POST, answered with JSON or SSE.

Is MCP the same as function calling? Not exactly. MCP is the transport and discovery layer — JSON-RPC 2.0, a tool list, capabilities — between an app and the programs around it.

Recommendation

Start with the official filesystem server in Claude Desktop, exactly as above. It is the shortest path to seeing the full loop work on your machine. If you need a cloud service or a database, prefer its hosted (Streamable HTTP) version. If you do one thing after reading this: open your MCP config, delete the servers you no longer use, and confirm you know where each remaining one comes from.

If you build the agent stack around local models, the runner picker matches a runtime to your OS, and the Agents and MCP pillar page collects the directory and guides. For the hardware side, see how to run Llama 3.1 8B on a 16 GB GPU.

Sources