What Is an MCP Server? A Complete Guide to Model Context Protocol Servers, Architecture, and Claude Integration

What Is an MCP Server?

An MCP Server is a server-side implementation of the Model Context Protocol (MCP) that exposes tools, resources, and reusable prompts to AI assistants such as Claude, Cursor, VS Code’s GitHub Copilot Chat, and Cline. Originally introduced by Anthropic in November 2024, MCP became an open standard maintained by the Agentic AI Foundation (under the Linux Foundation) starting December 2025.

If APIs are how applications talk to each other, MCP Servers are how AI models talk to the outside world. Think of an MCP Server as a “USB-C port for AI”: once your data source, internal tool, or SaaS product implements the protocol, any compliant client can plug in and operate it without bespoke integration. That single design choice has driven explosive adoption across IDEs, desktop AI clients, and enterprise tooling through 2025 and into 2026.

How to Pronounce MCP Server

How an MCP Server Works

MCP is built on top of JSON-RPC 2.0 and reuses many design ideas from the Language Server Protocol (LSP). When an MCP Client (e.g., Claude Desktop) launches an MCP Server, the two perform a capability negotiation handshake: each side advertises what it supports — tools, resources, prompts, sampling, logging — so the client can decide which features to enable. This is why a Claude Desktop user can drop a new server into their config and Claude will dynamically discover its tools at next launch.

The three primitives an MCP Server can expose

Among these, tools are the most heavily used. You declare each tool with a JSON schema — input parameters, return type, a natural-language description — and the AI client passes that schema to the model so it can decide when to call the tool. Notice how the schema doubles as documentation: a clear description helps the model use the tool correctly, which is important when designing tool names and parameter docstrings.

The lifecycle of an MCP session

An MCP session has a clear lifecycle worth understanding. After the initial handshake, the client periodically calls tools/list, resources/list, and prompts/list to refresh its catalog. The server can also push tools/list_changed notifications when its tool set changes — for example, when a user authenticates and gains access to additional functionality. Tool invocations follow a request/response pattern: the client sends tools/call with the tool name and arguments, the server validates against the declared schema, executes the work, and returns a structured result. Errors are returned as JSON-RPC error objects with codes that the client can interpret programmatically.

Resources work slightly differently. A resource has a URI (e.g., file:///etc/hosts or github://repo/owner/path), and the client requests its contents with resources/read. Servers can mark resources as subscribable so the client gets notified when contents change. The reason this design matters is that it lets a server expose live data — a streaming log file, an evolving Notion page — without forcing the AI to re-poll constantly. You should keep in mind that the resource model fits naturally into agentic workflows where the AI needs to reason over data that can change between observations.

The capability negotiation handshake in detail

When an MCP Client connects to an MCP Server, the very first JSON-RPC message is an initialize request. The client announces its protocol version, the features it supports (tools, resources, prompts, sampling, logging, roots), and any client-specific metadata. The server responds with its own version and the subset of features it implements. Both sides then send an initialized notification to confirm the handshake is complete. From that moment forward, the client knows exactly what it can ask the server to do, and the server knows what kind of client it’s talking to. This explicit negotiation is what makes MCP forward-compatible: a newer client speaking to an older server gracefully degrades, and vice versa.

An important architectural detail: the protocol distinguishes requests (which expect a response) from notifications (fire-and-forget). Tool calls are requests; log messages and progress updates are notifications. The reason this matters is that latency-sensitive flows can use notifications without blocking the request/response queue. It’s also why long-running tools should send progress notifications during execution rather than holding a single request open for minutes.

Transports: stdio, HTTP+SSE, and Streamable HTTP

MCP supports several transports. stdio is the default for local processes — Claude Desktop launches the server as a child process and pipes JSON-RPC over standard input/output. HTTP+SSE targets remote servers; the 2025-11-25 spec also adds Streamable HTTP for simpler bidirectional flows. In practice you should keep in mind that local development uses stdio while remote production uses HTTP transports with TLS and authentication.

MCP Server Usage and Examples

Basic Quick Start

The official Python SDK ships with the mcp package. A minimal MCP Server looks like this:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("weather-server")

@mcp.tool()
def get_weather(city: str) -> str:
    # Return the current weather for the given city
    return f"{city}: 72F, sunny"

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

Register this server in claude_desktop_config.json and Claude can call get_weather whenever it judges it relevant. You should production-harden this with authentication, structured logging, and per-tool error handling before exposing it to other users.

Common Implementation Patterns

Pattern A: Local filesystem access (stdio)

from mcp.server.fastmcp import FastMCP
import pathlib

mcp = FastMCP("local-fs")

@mcp.tool()
def read_file(path: str) -> str:
    p = pathlib.Path(path).expanduser()
    if not p.is_file():
        return f"File {path} not found"
    return p.read_text()

mcp.run()

Use this when: a single user wants AI access to their machine’s files, scripts, or local databases.

Avoid this when: multiple users need concurrent access — stdio is one process per session, so you should switch to HTTP for shared deployments.

Pattern B: Remote API wrapper (HTTP+SSE)

from mcp.server.fastmcp import FastMCP
import os, requests

mcp = FastMCP("github-issues")
TOKEN = os.environ["GITHUB_TOKEN"]

@mcp.tool()
def list_issues(repo: str, state: str = "open") -> list:
    # List issues in the given repository
    r = requests.get(
        f"https://api.github.com/repos/{repo}/issues",
        headers={"Authorization": f"Bearer {TOKEN}"},
        params={"state": state},
        timeout=30,
    )
    return r.json()

Use this when: you want a team or product to share access to an internal SaaS through MCP.

Avoid this when: authorization and per-user scoping aren’t yet designed; remember that an open MCP Server with a privileged token is effectively a confused deputy waiting to happen.

Anti-Pattern: Blindly Executing Shell Commands

# ⛔ Never do this
@mcp.tool()
def run_shell(cmd: str) -> str:
    import subprocess
    return subprocess.check_output(cmd, shell=True).decode()

Exposing a shell-execution tool to an AI is one of the fastest paths to remote code execution via prompt injection. Use allowlists, parameter validation, and confirmation prompts for any tool with side effects. It’s important to note that AI clients increasingly add per-tool consent UI, but you should not rely on that as your only defense.

Advantages and Disadvantages of MCP Servers

Advantages: a single MCP Server works across Claude Desktop, Cursor, VS Code, Continue, Cline, and Zed — write once, integrate everywhere. Schema-driven design makes tool calls type-safe and improves model accuracy. Open governance under the Agentic AI Foundation reduces vendor lock-in. Note that the standard library of community MCP Servers (filesystem, GitHub, Slack, Postgres, Notion, and many more) means you rarely have to start from scratch.

Disadvantages: the spec is still evolving, with occasional breaking changes between versions. Authentication, authorization, audit logging, and rate-limiting are out of scope of the protocol — you must build them yourself. The stdio transport is simple but doesn’t trivially extend to remote hosting; you should keep this in mind when planning multi-user deployments.

MCP Server vs. MCP Client vs. REST API Server

MCP Servers, MCP Clients, and traditional REST API servers are often confused. The table below shows how their roles differ.

The pithy summary: MCP Servers expose capability, MCP Clients consume it, and REST APIs serve general-purpose web clients. You should keep in mind that an MCP Server is designed for an AI to read and reason about — descriptions and schemas double as model documentation, which is a perspective shift most REST API authors aren’t used to.

Common Misconceptions About MCP Servers

Misconception 1: “An MCP Server is just a special HTTP server”

Why people are confused: the word “server” plus the example using mcp.run() looks superficially like Flask or Express, leading newcomers to assume MCP is HTTP. The reason is largely framing — most server-side tutorials they’ve seen are HTTP servers.

Correct understanding: stdio is the default transport. Locally, an MCP Server is just a subprocess speaking JSON-RPC over pipes — no port, no listener. HTTP transports exist for remote scenarios but they’re optional, not the baseline.

Misconception 2: “MCP is Anthropic-only”

Why people are confused: most early adopters first encountered MCP through claude_desktop_config.json, so the protocol got mentally tagged as a Claude feature. The historical reason is that Anthropic shipped the spec and the first reference clients.

Correct understanding: MCP is an open spec, donated to the Agentic AI Foundation in December 2025 with co-stewards including OpenAI and Block. Cursor, VS Code GitHub Copilot Chat, Continue, Cline, and Zed all ship MCP support.

Misconception 3: “MCP replaces RAG”

Why people are confused: both are talked about as ways to “give the model external knowledge,” and many blog posts conflate them.

Correct understanding: RAG injects retrieved chunks into the prompt; MCP provides on-demand tool/resource access. They compose well — an MCP Server can wrap a RAG pipeline as a single search_docs tool. The reason they coexist is they target different latency and freshness profiles.

Real-World Use Cases

Production patterns that have emerged: an internal Postgres MCP Server lets analysts ask Claude SQL questions; a Linear/Jira MCP Server turns natural-language tickets into structured updates; a Slack MCP Server posts incident summaries. Engineering teams wrap their CI/CD systems with MCP so AI can trigger jobs and read logs. Data teams expose ETL pipelines as MCP tools so non-engineers can describe a desired transformation in plain English and have it produce the correct dbt or Airflow job. Customer-success teams expose Zendesk and Intercom through MCP to let support engineers ask “show me every ticket from this customer in the last 30 days that mentions latency.”

Outside engineering, MCP Servers are powering knowledge-work patterns that previously required custom scripting. Finance teams expose Quickbooks or Xero via MCP for natural-language reporting; legal teams put Lexis or Westlaw behind MCP so an associate can ask Claude to “find me precedents about indemnity caps in SaaS contracts” without leaving the chat window. The pattern that wins repeatedly is wrapping internal systems — generic AI clients can already reach the public web, so the highest-leverage MCP Servers are the ones that bridge proprietary or sensitive data sources. It’s important to note that early adopters report the largest productivity gains come not from sophisticated AI reasoning, but simply from removing the friction of manual lookups across siloed tools.

The Linux Foundation’s Agentic AI Foundation also runs a public registry of community MCP Servers, which means most common needs (filesystem, GitHub, GitLab, Postgres, MySQL, Notion, Slack, Sentry, Cloudflare, Stripe, Brave Search, Google Maps, and many more) already have an open-source implementation you can install in seconds. You should keep in mind that pulling third-party servers means trusting their authors with whatever credentials you provide — pin to specific versions, review the source, and audit token scopes.

Production patterns that have emerged: an internal Postgres MCP Server lets analysts ask Claude SQL questions; a Linear/Jira MCP Server turns natural-language tickets into structured updates; a Slack MCP Server posts incident summaries. Engineering teams wrap their CI/CD systems with MCP so AI can trigger jobs and read logs. It’s important to note that the highest-leverage MCP Servers usually wrap your internal systems — the ones a generic AI client can’t reach. That’s where MCP earns its keep in real organizations.

Designing tools that AI uses well

One of the under-discussed lessons of MCP adoption is that AI-friendly tool design differs from human-friendly API design. The clearest pattern is verbose, descriptive parameter docs: a tool whose schema includes “the absolute path to the file (must start with /)” performs measurably better than one annotated with just “path”. The reason is that the AI uses the description as runtime guidance, not just for documentation. Concise but explicit prose pays off in fewer mistaken calls.

Another pattern is idempotent operations. AI agents may retry tool calls when an answer feels unfinished, so a tool that creates a new record on every call (even with the same arguments) ends up creating duplicates. Designing tools so repeated calls converge on the same state — or returning a stable identifier the AI can recognize — meaningfully improves agent reliability. You should keep in mind that this kind of design discipline is what separates “I built an MCP Server” from “my MCP Server is reliable in production.”

Security considerations for MCP Server authors

Security in MCP is the implementer’s responsibility, and the protocol gives you the seams you need but no defaults. The first principle is least privilege: each tool you expose should require the minimum permissions necessary. If a tool only reads, don’t give it write credentials. If a tool only operates on a single user’s data, scope its credentials per-user. Note that this applies even more strictly when an HTTP MCP Server is shared across users — a single over-privileged tool becomes a confused-deputy attack waiting to happen.

The second principle is treat AI input as untrusted. The model deciding which tools to call is itself susceptible to prompt injection: a malicious document the model reads can persuade it to call delete_user or send_money. The mitigation is to put confirmation prompts in the client UI for any tool with side effects. Major MCP clients (Claude Desktop, Cursor) implement this — when a tool is marked as having side effects, the user must approve each call. Your server should mark tools accordingly via the annotations field. The reason these mitigations matter is that without them, an attacker who can put text in front of your AI can effectively use it as a remote weapon.

The third principle is auditability. Every tool invocation should be logged with enough context to reconstruct what happened — user, timestamp, tool name, arguments, return value, error. For high-risk operations, log to an append-only store (S3 with object lock, immutable database, or a SIEM). You should keep in mind that in regulated environments, the audit log is often the primary evidence that the AI’s actions were policy-compliant.

Frequently Asked Questions (FAQ)

Conclusion

• An MCP Server exposes tools, resources, and prompts to AI clients via the open Model Context Protocol.
• The protocol is JSON-RPC 2.0 with capability negotiation, inspired by LSP, and now governed by the Agentic AI Foundation.
• Transports include stdio (local default), HTTP+SSE, and Streamable HTTP (added in the 2025-11-25 spec).
• Official SDKs cover Python, TypeScript, C#, Java, Kotlin, and Swift; the same server runs across Claude Desktop, Cursor, VS Code, Cline, and more.
• Security is the implementer’s responsibility — expect to add auth, allow-listing, audit logging, and human-in-the-loop confirmations.

References