#1MCP (Model Context Protocol) explained for developers

What we tested: We counted tokens across multiple model families (GPT-4o, Claude, Gemini) using our LLM token counter. Prompt caching behavior was tested with repeated inputs of varying length.

MCP, or Model Context Protocol, is a standard way for AI clients to discover tools, resources, and prompts exposed by a server.

The real value is not the acronym itself. It is the contract: define one capability once, then let compatible clients reuse it without custom glue for each app.

If you have built agent tooling before, a fair mental model is “LSP for AI tools”: one common protocol for connecting clients to capabilities.

#2Why MCP exists

Before MCP, every agent framework defined its own tool format. A tool written for LangChain didn’t work in Claude Desktop, which didn’t work in your custom agent, which didn’t work in Cursor. Each integration was bespoke, every prompt-engineered "function description" was framework-specific, and every team rebuilt the same wheel.

The pain points MCP solves:

• Fragmentation. Five frameworks, five tool formats. Five times the work.
• No discovery. Clients couldn’t enumerate what a tool server offered without a hard-coded manifest.
• No portability. A debugging assistant you wrote for one agent wouldn’t move to another.
• Auth was ad hoc. Every integration invented its own way to handle API keys and OAuth.

MCP makes the contract uniform: a server declares its tools, resources, and prompts; a client speaks the same JSON-RPC dialect to discover and call them. The same MCP server that ships with Anthropic's TypeScript SDK today will work with any future client that implements the spec, regardless of which LLM the client uses underneath.

#2The Wire Protocol in One Page

MCP rides on JSON-RPC 2.0, which means every message is a JSON object with a jsonrpc: "2.0" envelope, a method, optional params, and an id for requests that expect a response.

There are two supported transports:

1. stdio. The client launches the server as a subprocess and they communicate over stdin/stdout. This is how Claude Desktop and Cursor talk to local MCP servers configured in your mcp.json or claude_desktop_config.json.
2. HTTP + SSE (Server-Sent Events). Network-reachable. The client POSTs JSON-RPC requests to a single endpoint, and the server can stream notifications back over Server-Sent Events. This is the transport that browser tools, including the AllDevToolsHub MCP Server Tester, can reach directly.

A normal session looks like this:

1. initialize, client sends its protocol version and capabilities; the server responds with its version and capabilities.
2. notifications/initialized, client confirms readiness.
3. Discovery and invocation, tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get, plus pings and notifications.
4. Connection closes, either side hangs up.

The protocol is symmetric. Servers can also send requests to the client, for example, asking the model for completions on the server's behalf (the "sampling" feature), though that is an advanced pattern most servers do not use.

#2The Tools / Resources / Prompts Triad

Almost every capability an MCP server exposes falls into one of three buckets. Understanding which is which is the single biggest unlock for building servers that feel natural to use.

#31. Tools, the function-call surface

Tools are functions the model invokes with arguments. Same shape as Claude tool use or OpenAI function calling, name, description, JSON Schema input:

{
  "name": "get_weather",
  "description": "Get current weather for a city.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "city": { "type": "string", "description": "City name" }
    },
    "required": ["city"]
  }
}

The model reads the description, decides when to call, and the client dispatches tools/call with the chosen arguments. The server runs the tool and returns content blocks.

Common gotchas:

• Vague descriptions. "Get data", the model can't tell what data, or when. Be specific: "Returns the current weather (temperature, conditions) for a named city. Use when the user asks about weather."
• Missing required. Without it, models may call with no arguments and confuse themselves.
• Wrong response shape. Tools should return { content: [{ type: "text", text: "..." }] } or other typed content blocks. Returning a bare string violates the spec, and strict clients reject it.

#32. Resources, the read-only context surface

Resources are pieces of data the model can pull into context, files, database rows, API responses. They are identified by URI:

{
  "uri": "file:///path/to/log.txt",
  "name": "Recent log",
  "description": "Last 24 hours of application logs.",
  "mimeType": "text/plain"
}

resources/list enumerates available URIs; resources/read fetches a specific one. Resources differ from tools in three important ways:

• Read-only. No side effects (by spec).
• Addressable. The URI is stable, the same resource can be read repeatedly.
• User-discoverable. Many clients surface resources in their UI so the user can attach one manually, separate from model-initiated reads.

Servers can also push change notifications when subscribed-to resources update (resources/subscribe), useful for log tails or live dashboards.

#33. Prompts, the user-invoked workflow surface

Prompts are templates the user (not the model) invokes, typically via slash commands or template buttons in the client UI:

{
  "name": "summarize_pr",
  "description": "Summarize a GitHub pull request.",
  "arguments": [
    { "name": "pr_url", "description": "GitHub PR URL", "required": true }
  ]
}

The user picks the prompt, fills in arguments, and the server returns a prompt body, usually a system + user message pair, that the client sends to the model. Prompts are how MCP servers expose pre-engineered workflows: a system prompt plus tool guidance plus parameters, packaged so the user gets the right behaviour in one click.

#2The Most Common MCP Errors

JSON-RPC defines a small set of standard error codes; MCP layers a few transport quirks on top. If you build a server, expect to see all of these at some point.

A debug-time tester that speaks the wire protocol, like the MCP Server Tester, catches all of these before they bite you inside a real agent loop.

#2MCP vs. Other Tool-Use Approaches

MCP is one of several ways to give models tools. The right answer depends on scope.

#3APIs, function calling, and MCP: three distinct layers

A lot of AI architecture confusion comes from treating every "tool integration" problem as the same. In reality, there are three distinct questions:

1. How do services talk to each other? APIs. REST, GraphQL, gRPC, webhooks. Explicit contracts, versioned behavior, the backbone of service communication.
2. How does a model decide which callable function to use? Function calling. The model reads a description and input schema, then chooses whether to invoke the function. Model-specific, not a transport protocol.
3. How do we standardize tool discovery and invocation across agents and clients? MCP. Cross-client, cross-framework, with tools, resources, and prompts.

APIs remain the primary interface for application integration. Function calling and MCP are layers on top of or around APIs, not replacements.

#3Other approaches compared

• Native function calling (Claude tool use, OpenAI functions, Gemini functions): per-conversation, per-application. Lightest weight when your tools live inside one app and you do not need to share them.
• LangChain / framework tools: works inside that framework. Does not cross frameworks; rewriting for a different agent runtime is manual.
• OpenAPI specs as tools: REST APIs described once, called by anything that understands OpenAPI. Strong for read-heavy, request/response surfaces. Less interactive, no streaming, no notifications, no user-invoked prompts.
• MCP: cross-application, cross-framework, with a typed surface that includes tools and resources and prompts. Heavier than a single function call, lighter than a full REST integration.

The rule of thumb: if the same capability will be used by more than one client or more than one team, build it as an MCP server. If it is single-app and single-team, native function calling is simpler.

#2Getting Started, Build Your First MCP Server

Anthropic ships SDKs in TypeScript, Python, Kotlin, Swift, and Java. A working TypeScript server is about twenty lines:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({ name: "my-server", version: "1.0.0" });

server.tool(
  "greet",
  { name: z.string() },
  async ({ name }) => ({
    content: [{ type: "text", text: `Hello, ${name}!` }]
  })
);

await server.run(); // stdio by default

Drop that into your Claude Desktop or Cursor mcp.json config, restart the client, and the greet tool is live. The model will call it when a user says "say hi to Sarah."

A natural development loop:

1. Write a tool in the SDK of your choice.
2. Connect the MCP Server Tester to your HTTP endpoint (or wrap a stdio server with a small HTTP shim) and exercise the wire protocol directly. You see exactly what an agent will see, initialize, tools/list, tools/call, without having to drive a full agent loop.
3. Iterate on descriptions and schemas until the model picks the right tool with the right arguments.
4. Wire it into your client of choice once the protocol looks clean.

If you are still building intuition for what tokens and tool calls look like on the wire, the JWT Decoder and the HTTP Headers Reference cover the auth surface that an MCP server with OAuth 2.1 will sit on top of.

#2Frequently Asked Questions

#3What is an MCP server in plain English?

An MCP server is a small program that exposes a set of capabilities, functions to call, files to read, prompt templates to run, over a standardized JSON-RPC 2.0 protocol. AI agents like Claude or Cursor connect to it the same way they connect to any other MCP server, regardless of who wrote it. You can think of it as "a typed plugin for AI agents that any compatible agent can use."

#3Does MCP only work with Claude?

No. MCP is an open specification and is deliberately model-agnostic. Any client that implements the protocol, Cursor, Zed, Sourcegraph Cody, your own agent, can use any MCP server, regardless of which underlying LLM the client is wired to. A server you write today will keep working with future clients running OpenAI, Gemini, Llama, or anything else, as long as those clients speak MCP.

#3What is the difference between stdio and HTTP+SSE transports?

stdio is process-to-process: the client launches the server as a subprocess and they talk over stdin/stdout. It is the common transport for local servers running alongside Claude Desktop or Cursor. HTTP + SSE is network-reachable: the client POSTs JSON-RPC requests to a single endpoint, and the server streams notifications back over Server-Sent Events. Stdio is faster and simpler for local tools; HTTP+SSE is what you use when the server lives on another machine, behind auth, or in a serverless function.

#3How does authentication work in MCP?

The 2025-03-26 revision of MCP added first-class OAuth 2.1 support for HTTP transport. A protected server returns 401 Unauthorized with a WWW-Authenticate header that points at a metadata endpoint; the client follows the discovery handshake to obtain a token, then sends it as Authorization: Bearer <token> on subsequent requests. For development, many servers also accept a static API key with the same Authorization: Bearer style.

#3What are the most common MCP server bugs?

The top three, in order of frequency: (1) stdio framing corruption caused by logging to stdout instead of stderr, the symptom is a -32700 Parse error on the first message. (2) tools/list returns nothing because the server starts up but the server.tool(...) registration calls never ran. (3) Vague tool descriptions that the model cannot match to user intent, so the tool is registered but never called. A wire-level tester catches all three in seconds; a full agent loop hides them behind silent failures.

MCP is the first credible attempt at a universal contract between AI agents and the systems they act on, and the ecosystem is moving fast, new clients, new servers, and new spec revisions every few months. The fastest way to keep up is to build one, then exercise it on the wire.

Test your MCP server against the live protocol now at the AllDevToolsHub MCP Server Tester, no install, no telemetry, the JSON-RPC traffic stays in your browser tab. Or browse the AllDevToolsHub Glossary for the surrounding vocabulary (JSON-RPC, SSE, OAuth 2.1, JWT).

Written by Rahul Jalavadiya, founder of AllDevToolsHub. All tools run locally in your browser.

#2Sources / Further reading

• Model Context Protocol - Official specification
• Anthropic - Introducing MCP
• IETF - RFC 8259: JSON