MCP Beginner Tutorial

MCP stands for Model Context Protocol, an open standard protocol used to standardize how AI applications connect to external tools and data sources.

MCP is like USB-C: it allows different devices to connect together through the same interface.

Before MCP existed, every time a new tool (such as GitHub, Slack, or a database) was integrated, each AI application had to write its own set of integration code, resulting in theN × M integration problem(N AI applications × M tools = N×M sets of code).

With MCP, the tool provider only needs to build one MCP Server following the standard, and any AI application that supports MCP can use it directly, becoming1 Server + compatible with all Hosts。

The following diagram intuitively shows the difference between traditional N×M integration and MCP standardized integration:

In December 2025, MCP was donated by Anthropic to the Agentic AI Foundation (AAIF) under the Linux Foundation, becoming an open standard shared by the industry. Vendors such as OpenAI and Block jointly participate in its governance.

Development Timeline

Core Architecture: Host / Client / Server

MCP draws on the design approach of LSP (Language Server Protocol, a protocol that gives editors unified support for programming languages) and defines three roles:

The relationship of the three-layer architecture is shown in the following diagram:

The underlying communication uniformly usesJSON-RPC 2.0message format, ensuring standardized interaction between different roles.

Detailed Explanation of the MCP Communication Flow

Taking "the user asks AI to check the weather" as an example, a complete tool call process is as follows:

The process is divided into seven steps:

1. User asks a question: The user enters "Check the Beijing weather for me" in the Host (such as Claude Code).
2. Model determines: The large language model built into the Host analyzes the question, determines that the weather query tool needs to be called, and sends the call intent to the Client.
3. Protocol translation: The Client converts the tool call request into a JSON-RPC 2.0 format message and sends it to the corresponding Server.
4. Server executes: After receiving the request, the Server performs the actual operation (such as calling a weather API or querying a database).
5. Return result: The Server returns the result to the Client in JSON-RPC format.
6. Hand back to the model: The Client passes the result back to the Host for the model to incorporate into its answer.
7. Answer the user: The model integrates the data returned by the tool with natural language and outputs the final answer.

Throughout the entire process, the Server is completely unaware of the existence of the large language model—it only processes JSON-RPC messages. This is the key design that enables MCP to be model-agnostic.

Three Core Primitives

An MCP Server can expose three types of capabilities externally, called "primitives":

In addition, there are two advanced mechanisms:

• Sampling: The Server, in turn, can request the Host's model to generate content for it, achieving a role reversal.
• Elicitation: When the Server discovers that information is insufficient midway through execution, it can proactively ask the user for clarification, for example, "Which date should I filter by?"

When starting out, you can just focus on Tools and Resources. It's not too late to learn about Prompts, Sampling, and Elicitation later when you need them.

Transport Methods

MCP supports two transport methods, suitable for different scenarios:

For personal learning and local development, usestdiois sufficient.

For enterprise-level scenarios requiring multi-user sharing, useStreamable HTTP。

All demonstration cases in this tutorial use the stdio method.

Security Notes

MCP gives AI the ability to execute code and access real systems, so security guidelines are especially important:

• Tool descriptions themselves are not trustworthy: Unless they come from a trusted Server, feature descriptions may be maliciously tampered with (prompt injection risk). The Host should remain vigilant about tool descriptions.
• Explicit user consent must be obtained: Sensitive operations must not be executed silently; every tool call should be confirmed by the user.
• Strengthen protection in production environments: The Server should be deployed as an OAuth resource server, combined with TLS encryption, access control, and log auditing.
• Third-party Servers must be reviewed: Confirm the source is trustworthy before use, and use sandbox isolation when necessary.

Hands-on Demo: Connecting Claude Code to an MCP Server

Below are two complete examples showing how to write an MCP Server and connect it to Claude Code.

The first example uses Python to write a weather query service, and the second uses Node.js/TypeScript to write todo list management.

Case 1: Python Weather Query Server

Goal: Write an MCP Server that provides a weather query tool, called through Claude Code.

Environment Preparation

pip install mcp httpx

Two Python packages need to be installed:mcpIs the official MCP Python SDK,httpxUsed to make HTTP requests to call the weather API.

Writing the Server Code

Create the fileweather_server.py：

Code Explanation:

• @mcp.tool(): Registers the function as a Tool; the docstring is automatically provided to the LLM as the tool description, helping the model decide when to call it.
• @mcp.resource(): Registers the function as a Resource for the model to read on demand; it does not involve "execution", only "lookup".
• mcp.run(transport="stdio"): Communicates with the Host via standard input/output, the most common method for local tools.

Local Debugging (Optional but Recommended)

Before connecting to Claude Code, use the official MCP Inspector tool to debug the Server and confirm it works properly:

npx @modelcontextprotocol/inspector python weather_server.py

After running, a web debugging interface opens automatically, where you can see which Tools and Resources the Server exposes and manually invoke them for testing.

It is recommended to go through the Inspector debugging process every time to troubleshoot code issues before connecting to a real AI assistant, which can save a lot of debugging time.

Configuring the MCP Server in Claude Code

Method 1: Have the AI Add It Directly

We can start Claude directly:

claude

Enter the following information and let Claude configure and add it for us:

添加 @weather_server.py 这个 MCP 服务

This is the simplest; after entering the prompt, the configuration and dependencies are completed automatically.

You can see that the configuration information was automatically generated in the .mcp.json file in the current directory:

After configuration is complete, ask directly in Claude Code:

Help me check the current weather in Beijing

If you prefer to tinker with things yourself, you can also use command-line addition and file configuration.

Method 2: Command-Line Addition

Note that the command and file paths need to be modified by yourself:

claude mcp add weather python /Users/example/example-test/weather_server.py

The meaning of this command:

• claude mcp add: The MCP management subcommand of Claude Code.
• weather: Give this MCP Server a name for later use.claude mcp listYou can see.
• python: The command to start the Server.
• /Users/.../weather_server.py: The absolute path to the Server script.

After successful addition, you can use the following command to view the connected MCP Servers:

claude mcp list

Example output:

NAME      STATUS   COMMAND
weather   active   python /Users/example/example-test/weather_server.py

To remove a Server:

$ claude mcp remove weather

Method 3: Configuration File (Suitable for Team Sharing)

Create it in the project root directory.mcp.jsonfile:

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["/Users/example/example-test/weather_server.py"]
    }
  }
}

After saving, restart Claude Code (or reopen the project) and the configuration takes effect.

The advantage of the configuration file approach is that it can be committed to the Git repository, and team members automatically get the same MCP Server configuration after cloning the project.

If a user-level MCP Server is configured (stored in ~/.claude/mcp.json), it takes effect for all projects. The project-level .mcp.json only takes effect for the current project.

Actual Usage

After configuration is complete, ask directly in Claude Code:

> Help me check the current weather in Beijing

Claude Code will automatically:

1. Identify that the get_weather tool of the weather Server needs to be called.
2. Pop up an authorization confirmation dialog asking whether to allow the call.
3. After you click Agree, it calls the Server to get the weather data.
4. Integrate the results into a natural language response.

This is the complete closed loop from the model to real-world data.

Case 2: Node.js/TypeScript Todo Server

If you are more familiar with the JavaScript/TypeScript ecosystem, here is an MCP Server example in Node.js.

Environment Preparation

npm install @modelcontextprotocol/sdk zod

Writing the Server Code

Create the filetodo_server.ts：

The way to connect to Claude Code is exactly the same as the Python version.

We can start Claude directly:

claude

Enter the following information and let Claude configure and add it for us:

添加 @todo_server.ts 这个 MCP 服务

Then in the conversation say "Add a todo for me: buy the example tutorial", and Claude Code will call the add_todo tool.

Existing Ecosystem: You Don't Have to Write Everything Yourself

Since MCP's release, the community has published over 500 public Servers, covering the vast majority of common scenarios:

The official SDK covers the following programming languages: TypeScript, Python, C#, Java, Swift.

In actual development, for most scenarios you can simply find an existing Server and use it. Only when connecting to internal company systems or private databases do you need to write your own MCP Server.

FAQ

References

• Official documentation:https://modelcontextprotocol.io
• Official specification:https://modelcontextprotocol.io/specification
• Official GitHub (includes SDKs and reference implementations in various languages):https://github.com/modelcontextprotocol
• MCP protocol:https://www.example.com/np/mcp-protocol.html
• Debugging tool Inspector:npx @modelcontextprotocol/inspector