MCP Server & Model Context Protocol Guide

What the Model Context Protocol is

The Model Context Protocol (MCP) is an open standard for connecting AI assistants to external tools and data. A client (Claude Code, Claude Desktop, an IDE, your own agent) connects to an MCP server, finds out what the server offers, and the model then calls those capabilities. One server serves every client that supports the protocol. For broader AI development concepts, see AI Development .

When to use it

• The model should work with your own system — a database, a CMS, a ticketing system, an internal API
• Several clients or agents should use the same integration
• You are debugging a connection between an MCP client and server
• You are deciding whether a new capability should be a tool, a resource or a prompt

Architecture

• Host — the application the model runs in (Claude Code, an IDE, a chat application).
• Client — the part of the host that holds the connection to one server. One client per server.
• Server — the program that offers capabilities. Messages are JSON-RPC 2.0.

A server offers three kinds of capabilities:

In the other direction, a client can offer the server sampling (the server asks for text generated by the model), roots (directories it may work with) and elicitation (a question to the user).

Transports

• stdio — the client starts the server as a subprocess and talks over standard input and output. For local tools; no network and no authentication.
• Streamable HTTP — the server runs on its own at a URL and serves several clients. For remote and shared servers; authentication (OAuth or a token in a header) belongs with it.

The older HTTP+SSE transport is replaced by Streamable HTTP in the specification; do not use it for new servers.

Your own MCP server in Python

pip install "mcp[cli]"

# server.py
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("demo")


@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two integers."""
    return a + b


@mcp.resource("note://{name}")
def note(name: str) -> str:
    """Return a note by name."""
    return f"Content of note {name}"


@mcp.prompt()
def review(code: str) -> str:
    """A code review task."""
    return f"Review this code and list the bugs:\n\n{code}"


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

The type annotations and the docstring are not decoration: the SDK builds the tool’s JSON schema and description from them, and the model decides from those when and how to call the tool. For HTTP, mcp.run(transport="streamable-http") is enough.

Connecting a client

# Claude Code — a local server over stdio
claude mcp add demo -- python /abs/path/server.py

# Claude Code — a remote server over HTTP
claude mcp add --transport http notes https://example.com/mcp

claude mcp list                 # connected servers and their status

Configuration shared with the team belongs in a .mcp.json file in the project root:

{
  "mcpServers": {
    "demo": {
      "command": "python",
      "args": ["/abs/path/server.py"],
      "env": { "API_TOKEN": "${API_TOKEN}" }
    }
  }
}

Debugging

npx @modelcontextprotocol/inspector python server.py

MCP Inspector opens a web interface where you can list the server’s tools, resources and prompts and call them by hand — without a model and without a client. It is the fastest way to find out whether a problem is in the server or in the client’s configuration.

Protocol method reference

A connection always starts with initialize: both sides exchange the protocol version and their capabilities — the list of what each supports. Do not call a method the other side did not announce.

Common mistakes