Understanding MCP
Learn how Model Context Protocol connects AI apps to tools, resources, prompts, and real-world systems without building a custom integration for every single assistant.
// MCP tool invocation over JSON-RPC { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "github_create_issue", "arguments": { "repo": "lida/rag-demo", "title": "Fix retrieval threshold docs" } } }
Why MCP exists
Without a shared protocol, every AI application needs custom glue code for every data source and every external action. MCP gives AI applications a common, standardized way to discover tools, read resources, and use reusable prompts across the entire development ecosystem.
Before MCP
Every assistant needs one-off integrations: a GitHub adapter here, a database adapter there, a filesystem connector somewhere else. Development is fragmented, and every new AI tool requires reinventing the wheel to access your data.
With MCP
A host connects to one or more MCP servers. The host discovers capabilities, then routes requests through a standard JSON-RPC protocol. You write an integration once, and any MCP-compatible AI assistant can immediately utilize it.
The catch
MCP makes tool access incredibly easy, which means permissions, user approvals, strict scoping, comprehensive logging, and prompt-injection defenses become absolutely critical to safe operation.
MCP architecture in one picture
Think of MCP as a client-server protocol built around an AI host. The host manages the underlying model and the user experience. MCP servers expose specific capabilities. The client connection handles discovery, calls, and results.
MCP Call Simulator
Choose a scenario and watch how initialization, discovery, permission checks, tool calls, and results work. Everything here is deterministic demo logic. No external API is called.
What actually happens during an MCP session
The protocol flow is simple but vitally important. Initialization negotiates capabilities between client and server. Discovery tells the host what exactly exists. Tool calls execute structured operations. Notifications keep the host continuously updated about state changes.
Initialize
Client and server exchange protocol versions, identities, and supported capabilities to establish a valid connection.
List
The client calls list methods (like tools/list, resources/list, or prompts/list) to discover exactly what the server exposes.
Call or read
The client invokes tools/call or reads resources dynamically after the host evaluates and chooses what it needs.
Notify
Servers can spontaneously notify clients when available tools, resources, or other capabilities change over time.
Tools, resources, and prompts
Most confusion around MCP disappears completely when these three server-side primitives are clearly understood and separated.
| Primitive | What it is | Example | When to use it |
|---|---|---|---|
| Tool | An executable action with a strictly defined input schema that the model can invoke. | create_issue, query_database, send_slack_message | When the AI needs to perform an active task, change state, or dynamically compute a result. |
| Resource | Readable contextual data or files exposed safely by a server. | file contents, DB schema, application logs, internal docs | When the AI simply needs to read information to gain context without changing state. |
| Prompt | A reusable template or workflow instruction provided by the server. | debug_api_error, review_pr_template | When you want to enforce a repeatable, domain-specific workflow or predefined instruction set. |
Security is not optional
MCP gives models unprecedented access to real tools and real data. That is powerful, but it means bad tool descriptions, overly broad permissions, or prompt injection can rapidly become real operational risks.
Scope every tool
A tool vaguely named run_sql is extremely dangerous. A tool specifically named read_customer_by_id with a strict validation schema is safe, predictable, and easier to reason about.
Require approval for writes
Read-only tools can often be automated safely. However, destructive or external write actions (like sending emails or deleting records) should always require explicit human-in-the-loop confirmation.
Treat tool output as untrusted
Documents, web pages, support tickets, and issue bodies can contain malicious prompt injection. Do not blindly follow instructions found in tool output, and isolate untrusted data.
Production readiness checklist
Common MCP server shapes
Different servers should expose different levels of power. A highly effective MCP server feels like a small, strongly-typed API specifically designed for an assistant, rather than a massive administrative console dumped into the model's context window.
Resource gateway
A read-only context server dedicated to safely exposing docs, files, database schemas, application logs, or internal knowledge bases.
Tool adapter
Wraps a single external service with a few highly focused tools. Examples include managing GitHub issues, querying Jira tickets, or resolving Sentry events.
Workflow orchestrator
Combines multiple complex operations into one safe, high-level workflow, such as “gather logs, summarize errors, and open a bug report.”
MCP anti-patterns
Avoid these common pitfalls when designing tools and resources to ensure your AI assistants remain secure and reliable.
One giant tool
Providing an "execute_anything" tool forces the model to reason about far too much freedom, leading to hallucinations. Always split broad capabilities into smaller, safely scoped actions.
Vague schemas
If tool parameters are loose strings without constraints, the model will inevitably produce invalid calls. Always use strict enums, length constraints, clear descriptions, and robust server-side validation.
Too many tools
Dumping dozens of similar or overlapping tools into the context window confuses the model and makes tool selection harder. Prefer a highly curated, minimal tool surface.
Returning secrets
Never return authentication tokens, user credentials, private keys, or internal infrastructure secrets as part of a tool's output to the model.
No source boundaries
Resource servers must strictly enforce access control. They need to securely know which roots, folders, projects, users, or database tenants the current user is actually allowed to read.
No audit trail
Visibility is crucial. You always need to know precisely who asked for an action, what tool was invoked, with which exact parameters, and what the final outcome was.
MCP FAQ
Is MCP the same as an API?
Is MCP the same as function calling?
When should I expose a tool versus a resource?
Should write actions be fully automatic?
Can MCP connect safely to private or sensitive data?
Does using MCP automatically remove security risks?
What is the best way to start building a first MCP server?
What is the primary difference between STDIO and HTTP transports?
Core MCP terms
MCP Host
The primary AI application (like an IDE or chat interface) that manages the user experience, controls the model context window, and enforces security boundaries.
MCP Client
The internal component living inside the host application that actively maintains a protocol connection to one or multiple MCP servers.
MCP Server
An external program or service that securely exposes tools, resources, and prompts to connected MCP clients over a standard transport.
Tool
An executable function accompanied by a strict JSON schema, allowing the model to perform actions like query_database or create_issue.
Resource
Safe, readable contextual data exposed to the model, such as file contents, application logs, internal documentation, or database schemas.
Prompt
A structured, reusable template provided by the server that guides a repeated interaction, best practice, or specific domain workflow.
JSON-RPC
The underlying, stateless message format utilized by MCP for all requests, responses, and real-time notifications between clients and servers.
Transport
The communication channel carrying the JSON-RPC messages. Most commonly STDIO for local, sandboxed servers or Server-Sent Events (HTTP) for remote servers.
Capability negotiation
The initial handshake step where the client and server exchange versions and declare exactly what features and capabilities they support.
Learn more
A small set of official or practical references. Not a link dump.
Best starting point for hosts, clients, servers, layers, primitives, and transports.
Official MCP DocsServer conceptsUseful for understanding how servers expose tools, resources, and prompts.
Developer ToolMCP InspectorUseful for testing and debugging MCP servers during development.
SpecificationMCP SpecificationThe formal reference when you need exact protocol behavior.
SDKTypeScript SDKPractical SDK for building MCP clients and servers in TypeScript.
SDKPython SDKPractical SDK for building MCP clients and servers in Python.