What Is MCP? The Model Context Protocol Explained

TL;DR — MCP in 30 seconds

MCP, the Model Context Protocol, is an open standard that lets AI coding tools — Claude Code, Cursor, Claude Desktop, ChatGPT Desktop — query your local tools and data through a single, typed interface. Anthropic released it in November 2024 as the "USB-C port for AI applications." An MCP server exposes tools the agent can call and resources the agent can read; the client starts the server, speaks JSON-RPC to it, and hands the results back to the model. The ecosystem has moved from novelty to default in under 18 months. Stash ships its own MCP server so an agent can read your screenshots and screen recordings the way it reads your codebase.

Why MCP Exists

Before MCP, every AI tool reinvented integration from scratch. A Claude adapter for your database didn't port to Cursor. ChatGPT plugins solved discovery only for ChatGPT, and only for services willing to register with OpenAI. Anthropic's engineers called this the "M×N problem": M models wired to N tools, one pair at a time.

Three earlier approaches pointed at the answer without reaching it:

• Ad-hoc function calling. Each vendor shipped its own tool-calling format. Code written for one model didn't port to another.
• OpenAPI / REST adapters. Fine for cloud services, heavyweight for local tools — HTTP server, auth, TLS, versioning.
• ChatGPT plugins. Closed, cloud-hosted, vendor-approved. Retired within a year.

MCP's insight was to borrow from the Language Server Protocol (LSP) — the standard that unified editor tooling across VS Code, Vim, Emacs, and JetBrains. LSP solved the M×N problem for editors. MCP applies the same pattern to AI clients: write a server once, and every MCP-speaking client can use it.

How MCP Works

MCP is a message protocol built on JSON-RPC 2.0. Three concepts do most of the work.

Tools, Resources, and Prompts

Every MCP server exposes some combination of these three primitives:

Most servers focus on tools. Resources are useful when the client wants to browse data before asking the model. Prompts let a server ship opinionated workflows — a Postgres server can bundle a "summarize-this-table" prompt that the agent invokes on demand.

Transports: stdio, SSE, and HTTP

An MCP client and server need a channel to exchange JSON-RPC messages. The spec defines three:

Most developer-facing MCP servers use stdio. It has the simplest security model (the server runs as your user, on your machine, with your permissions) and the lowest setup cost (no ports, no TLS, no auth). Stash, filesystem, Git, Postgres, and Puppeteer all use stdio.

A typical exchange

When Claude Code starts, it reads your MCP config, spawns each server, and issues an initialize handshake. The server advertises its tools, resources, and prompts; the model sees them and can call them when relevant. A call looks like this:

// Client → Server
{"jsonrpc":"2.0","id":7,"method":"tools/call",
 "params":{"name":"stash.list_recent","arguments":{"n":5}}}

// Server → Client
{"jsonrpc":"2.0","id":7,"result":{
  "content":[{"type":"text","text":"[5 captures ...]"}]
}}

That's the whole protocol in miniature. The model sees structured tool definitions on input, emits tool-call requests, and receives structured responses.

The Three Classes of MCP Servers

Most production MCP servers fall into one of three buckets. Knowing which bucket a server occupies tells you what it's good for and what risks you're taking by installing it.

The context class is the youngest and the most underused. A codebase-aware agent without screen-aware context is half-blind: it sees your files but not the UI bug you're debugging, the terminal output you already saw, or the Figma you compared against. That's the gap Stash fills.

Using MCP with Claude Code and Cursor

Both editors support MCP natively and both use near-identical JSON config files. Once you've written one, porting to the other is mostly rename work.

Claude Code

Claude Code stores user-scoped servers in ~/.claude.json and project-scoped servers in .mcp.json at the repo root. The CLI command claude mcp add edits these files for you, but you can edit them by hand. A minimal project config:

// .mcp.json (checked into the repo)
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/code"]
    },
    "stash": {
      "command": "/Users/you/.local/bin/stash-mcp",
      "args": []
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

Environment variable expansion (${GITHUB_TOKEN}) lets you commit the file to a team repo without leaking secrets — each developer sets the variable in their shell. User-scoped servers land in ~/.claude.json under a projects key when you run claude mcp add.

Cursor

Cursor uses .cursor/mcp.json (project-scoped) or ~/.cursor/mcp.json (user-scoped). The schema is the same. A user-scoped file looks identical to the Claude Code example above. Cursor caps the number of concurrently visible tools at 40 across all servers, so installing a kitchen-sink server can crowd out more useful ones — prefer focused servers with small tool surfaces.

One-line installers

Mature MCP servers ship a one-line installer that writes the right config block into the right file. Stash's yourstash.ai/install-claude.sh configures Claude Code, Claude Desktop, and Cursor in a single command. If setup involves a 300-line README and manual JSON merges, expect pain.

MCP vs. Plain Tool Calls vs. Plugins

Portability is the column that matters most. An MCP server written today keeps working when a new client emerges — and when you switch between Claude Code and Cursor in the same week, which agentic coders do.

Notable MCP Servers

A partial tour of servers worth knowing about. Anthropic maintains the first six as reference implementations; the rest are community or vendor-maintained.

• filesystem — Read and write files in a directory you scope at startup. The default way to give an agent access to a project.
• git — Read commits, diffs, branches, and search history. Read-only by design.
• github — Full repo operations: issues, PRs, code search, Actions. Write-capable; use a scoped PAT.
• postgres — Read-only query execution with schema inspection. Pair it with a read replica.
• slack — Read channel histories and send messages. Useful for on-call agents.
• puppeteer — Browser automation. Navigate, click, screenshot, extract.
• stash — Your screenshots, clipboard history, and screen recordings, queryable by any MCP client. Local socket, no network.
• memory — Persistent key-value memory across sessions. Turns a stateless agent into a stateful one.

Stash's MCP Server for Captures

Most MCP servers expose a domain an agent can already reason about — files, databases, APIs. Visual context is the domain agents are worst at reasoning over, because a pasted screenshot arrives as pixels stripped of every piece of metadata that made it meaningful. Stash is an MCP server for that missing domain.

The server is local-only. It listens on a Unix domain socket at ~/Library/Application Support/Stash/mcp.sock, speaks the stash-1 protocol, and enforces a peer-auth allowlist so only approved MCP clients can connect. No network traffic — the agents talk to a process on your Mac, not a cloud relay.

Five tools do the work:

• stash.list_recent(n) — newest-first summaries of the last N captures (max 500). Compact payload the agent uses to triage.
• stash.search(query) — substring search across app name, window title, bookmark name, OCR'd text, and browser URL.
• stash.get_capture(id) — the full dossier for a screenshot: app, window title, URL, accessibility tree, dev context (cursor position, file path), annotation shapes, OS and display info.
• stash.get_bundle(id) — for a recorded video, returns the markdown report, per-frame metadata, and absolute paths to every frame image and the audio track.
• stash.render_plain(id) — token-minimal plain-text rendering for inline paste.

Every capture has a stable stash://bundle/<uuid> URI. An agent that sees that URI once — in a chat, a commit message, a PR comment — can re-query it across sessions. This is the piece that chat-upload workflows can't match: uploads are one-shot, MCP references are persistent.

Officially supported clients are Claude Code, Claude Desktop, and Cursor, each auto-configured by the one-line installer at yourstash.ai/install-claude.sh. Any other MCP-speaking client — Windsurf, Zed, ChatGPT Desktop, Codex CLI — works in principle via the same stdio bridge, pointed at the client's own config file.

Common Gotchas

MCP is young enough that the failure modes aren't yet documented in every tutorial. A few recur.

• Stale server processes. If a server crashes, the client doesn't always notice. Symptoms: tools listed but calls time out. Restart the client, or kill the server process — ps aux | grep mcp finds it.
• Config path differences. Claude Code uses ~/.claude.json plus .mcp.json. Claude Desktop uses ~/Library/Application Support/Claude/claude_desktop_config.json. Cursor uses .cursor/mcp.json. Each client needs its own entry.
• Auth scope creep. Scope tokens to the narrowest permissions the agent needs. A GitHub PAT with admin:org is a liability, not a convenience.
• Tool-count ceilings. Cursor caps visible tools at 40. Five kitchen-sink servers will crowd each other out. Prefer focused servers with small tool surfaces.
• Permissions prompts. Claude Code prompts before every tool call by default. For trusted local servers, allowlist tools in ~/.claude/settings.json under permissions.allow.