MCP Tutorial: Connect and Build a Model Context Protocol Server Safely

The Model Context Protocol (MCP) is an open standard that lets AI apps such as Claude or ChatGPT connect to outside data and tools in one consistent way. This MCP tutorial has two hands-on parts. First you connect an existing MCP server to Claude Code or Claude Desktop and limit it to one practice folder. Then you build a tiny server of your own with the official Python SDK, test it in the MCP Inspector, and plug it into Claude. Security runs through every step, because an MCP server is real software that can read files and act for you.

Everything below follows the official MCP and Claude documentation as read on 13 October 2026.

Related reading: MCP course, how to use Claude Code for beginners, and Claude Code subagents. Key terms used in this guide: model context protocol, tool use, and prompt injection.

What MCP is and who this tutorial is for

The MCP site compares the protocol to a USB-C port for AI applications: one standard plug instead of a custom cable for every device. Without it, each AI app needs its own integration for every calendar, database or file system. With it, a tool built once as an MCP server can work in any app that speaks MCP. The intro page lists Claude, ChatGPT, Visual Studio Code and Cursor among the apps that support it.

This guide is for curious beginners who can open a terminal and copy commands, and for people who already use an AI assistant and want it to work with their own files or tools. You do not need to be a professional developer. If you can install an app and edit a short text file, you can finish both parts.

One age note before you start: Anthropic’s consumer terms require Claude users to be at least 18, or older where local law sets a higher age.

Core concepts: hosts, clients, servers and tools

The architecture overview uses three roles:

• Host: the AI application you talk to, such as Claude Desktop or Claude Code.
• Client: a connector inside the host. The host creates one client for each server it connects to.
• Server: a program that offers context or actions to the AI. It can run on your computer (a “local” server) or on the internet (a “remote” server).

Messages between them use JSON-RPC 2.0, a simple format for requests and replies. They travel over one of two transports. Stdio connects two programs on the same machine through standard input and output. Streamable HTTP carries messages over the web, which is how remote servers work.

A server can expose three core building blocks, which the docs call primitives:

The protocol keeps moving. As of October 2026 the current protocol version is 2026-07-28, and the architecture page notes that the older sampling feature is deprecated in that version. Treat any tutorial written before mid 2026 with care, because some code in it may no longer match the SDKs.

How does MCP compare with other ways of connecting AI to tools? A plain web API is built for programs that already know exactly which endpoint to call. MCP adds a layer the model can read: each tool arrives with a name, a description and a list of inputs, so the AI can decide when to use it. The Python SDK’s README describes MCP as being like a web API, but designed for LLM interactions. The practical difference for you is reuse: one MCP server can serve several AI apps without rewriting the integration for each.

Before you start: tools, cost and a safety baseline

Here is what you need for both parts:

1. An MCP host. Claude Desktop, Claude Code, VS Code or Cursor all work. The examples use Claude.
2. Node.js. The local servers guide says many MCP servers, including the Filesystem Server, need it, and recommends the LTS version. The MCP Inspector needs Node 22.19.0 or newer.
3. Python and uv for Part 2. The SDK README asks for Python 3.11 or newer. Install uv, a Python project manager, from its official install page.

On cost: the protocol is an open standard, the SDKs are open source, and the Python SDK is MIT licensed according to its README. What you may pay for is the AI app itself. Check current plan pricing on the vendor’s own site before you subscribe.

Set up one safety habit now. Create an empty folder called mcp-practice in your home folder and copy in a few harmless test files, such as a shopping list or a sample letter. You will point every server in this tutorial at that folder only, never at your whole Desktop, Documents or home folder.

Step 1: connect an existing MCP server

The easiest first server is the official Filesystem Server, which lets Claude read and organize files in folders you name. The modelcontextprotocol/servers repository labels its servers as reference implementations meant for learning, not production-ready solutions. That is fine for a practice folder.

In Claude Desktop

Following the local servers guide:

1. Open the Claude menu in your system menu bar, choose Settings, then the Developer tab, then Edit Config.
2. The file opens at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows.
3. Add this entry. Replace /FULL/PATH/TO with the real location of your folder, which the pwd command prints when you run it inside the folder (on Windows, use double backslashes in the path):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem@1.0.0",
        "/FULL/PATH/TO/mcp-practice"
      ]
    }
  }
}

The @1.0.0 ending pins the version that was current on npm on 13 October 2026. Before you install, open the package page on npmjs.com, confirm the publisher and the latest version, and update the number here and in the Claude Code command below if it has changed.

4. Quit Claude Desktop completely and reopen it. Closing the window is not enough.
5. Click the “Add files, connectors, and more” button in the message box, open Connectors, and check that filesystem appears with its tools.

Now ask: “List the files in my mcp-practice folder.” The guide explains that Claude asks for your approval before it runs a file action. Read each request before you click allow, and deny anything you did not expect.

In Claude Code

Claude Code adds servers from the terminal. The Claude Code MCP quickstart shows the pattern: a name, then --, then the command that starts the server.

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem@1.0.0 /FULL/PATH/TO/mcp-practice
claude mcp list

claude mcp list should show the server as connected. By default the server is saved at local scope, which means it is private to you and active only in the current project. For a hosted server, the same guide uses --transport http with a name and the server’s web address. While testing a new server, start Claude Code with claude --permission-mode manual (or press Shift+Tab to Manual) so you approve each tool call.

In other clients

VS Code, Cursor and ChatGPT each document their own MCP setup, linked from the official MCP intro page. The concepts stay the same: name the server, give the start command or URL, limit what it can reach, and keep approvals on.

Step 2: build a tiny MCP server with the Python SDK

The MCP SDK page lists official SDKs in TypeScript, Python, C#, Go, Rust and Ruby (Tier 1), Java (Tier 2), and Swift, PHP and Kotlin (Tier 3). Python is the gentlest start, so this example uses it.

Set up the project

uv init study-helper
cd study-helper
uv add "mcp[cli]>=2"

The mcp[cli] install command comes from the SDK README, which explains that the cli extra adds the mcp command with mcp dev and mcp run. The >=2 part matters: this code needs SDK v2.

Write the server

Create a file called server.py with two small, harmless tools. Neither one touches your files or the internet:

from datetime import date

from mcp.server import MCPServer

mcp = MCPServer("Study Helper")

@mcp.tool()
def days_until(target: str) -> int:
    """Count the days from today until a date written as YYYY-MM-DD."""
    return (date.fromisoformat(target) - date.today()).days

@mcp.tool()
def word_count(text: str) -> int:
    """Count the words in a piece of text."""
    return len(text.split())

if __name__ == "__main__":
    mcp.run(transport="stdio")

What each part does:

• MCPServer("Study Helper") creates the server and gives it a name.
• @mcp.tool() turns an ordinary function into a tool. The SDK reads the type hints (target: str) to build the input schema, and the docstring becomes the description the AI reads to decide when to call the tool.
• mcp.run(transport="stdio") starts the server over stdio, the right choice for a server that runs on your own computer.

Test it in the MCP Inspector

Before you connect any AI, test the server on its own:

uv run mcp dev server.py

The README shows this command opening your server in the MCP Inspector, a browser tool that lists every tool and lets you call it by hand. Try word_count with a sentence, then days_until with a date. The Inspector page notes that it prints a URL with a per-launch access token, so do not share that link. Testing without a model in the loop shows you exactly what the server returns.

Connect your server to Claude

For Claude Code, register the command that starts it:

claude mcp add study-helper -- uv --directory /FULL/PATH/TO/study-helper run server.py

For Claude Desktop, add a second entry under mcpServers, next to filesystem:

"study-helper": {
  "command": "uv",
  "args": ["--directory", "/FULL/PATH/TO/study-helper", "run", "server.py"]
}

Restart the app and ask: “How many days until 2026-12-31?” Claude should call days_until. Worked example: on 13 October 2026, the answer would be 79 days. If you get that number, your server, the SDK and the host are all talking correctly.

Security: what to know before deciding which servers to trust

The official Local Server Security guide is direct: a local server is an ordinary program running with your account’s access. It can read files your account can read, see environment variables such as tokens, and connect to the internet. Stdio is not a sandbox. Five rules cover most of the risk:

1. Install only servers you can trace. Check the publisher, match the exact package name to avoid lookalikes, and pin a version you checked instead of always taking the newest one. A listing on npm or PyPI is not an endorsement.
2. Give the least privilege that works. Point file servers at one folder, read-only where possible. Give each server its own narrowly scoped token through its own config entry, such as a token limited to one repository rather than your whole account. Never reuse a broad personal token, and never paste passwords, ID numbers or card details into a config file or a chat.
3. Keep approvals on. In Claude Code, use Manual mode (claude --permission-mode manual or Shift+Tab) while you test a server, and review every tool call that sends, deletes, moves or pays for something. Do not switch on settings that auto-approve all tools for a server you have not read.
4. Watch for prompt injection. When a server fetches web pages, emails or documents, hidden text in them can try to steer the AI. The local security guide adds that tool descriptions themselves are instructions the model reads, and a server can change them after you approve it.
5. Never expose a local server. Keep personal servers on stdio. The security best practices page recommends stdio for local servers and, if you use HTTP, an authorization token or restricted local sockets. The local security guide warns that binding to 127.0.0.1 is not an authentication boundary. Never forward a port on your router or put a home MCP server on the open internet.

Each server’s tool list also takes space in every session, so remove servers you no longer use.

For extra protection, the local security guide suggests running third-party servers inside a container with nothing mounted except the folder they need, and with no network if they do not need one.

Common mistakes and troubleshooting

Most first-day problems fall into a few patterns:

• The server does not appear. Check the JSON for a missing comma or bracket, use absolute paths, and fully quit and reopen Claude Desktop.
• npx or uv is not found. Desktop apps may not see your terminal’s PATH. Put the full path to the program in command, which you can find with which uv on macOS or Linux and where uv on Windows.
• The server starts, then breaks. A stdio server must not print to standard output. The debugging guide warns that writing to stdout interferes with the protocol. Use Python’s logging module, which writes to standard error.
• You need to see what went wrong. Claude Desktop writes MCP logs to ~/Library/Logs/Claude on macOS and %APPDATA%\Claude\logs on Windows, according to the local servers guide. Look for mcp.log and a file named after your server.
• Copied code from an old tutorial fails. Older examples may use names that changed in the current Python SDK. Compare with the official README first.

Decision framework: local or remote, build or reuse

Use this checklist before adding any server:

The local security guide makes the same point about remote options: a server that only wraps an online service gains nothing from running on your laptop. Build your own server when no trusted one exists, or when you want a tool that does one narrow job for you.

Next step

Make your next session practical. Connect the Filesystem Server to your mcp-practice folder, ask Claude to sort three test files into subfolders, and approve each step. Then add one more tool to your study helper, such as a reading-time estimate, and test it in the Inspector before Claude ever sees it.

If you would like a guided path from everyday prompting to confident use of AI tools like these, short lessons at your own pace make it easier to keep going. Explore Coursiv AI lessons to build your skills step by step.

Related guides: how to build an AI agent and Claude for Gmail.

FAQ