MCP Servers: What They Are, Why They Matter, and What Can Go Wrong

10 min read Original article ↗

TL;DR

MCP is everywhere now. Cursor, Claude Desktop, VS Code, Windsurf. Every dev tool startup is announcing "MCP support" like it's a feature checkbox. But most developers' understanding stops at "it lets AI tools connect to stuff."

That's roughly correct. MCP (Model Context Protocol) is an open standard from Anthropic, now under the Linux Foundation, that defines how AI applications connect to external tools and data sources. JSON-RPC wire format, SDKs in seven languages, and a fast-growing server ecosystem.

This post covers how the protocol actually works (with real JSON-RPC messages), the security risks nobody's talking about, and what this means if you maintain documentation.

What Problem Does MCP Solve?

Before MCP, connecting AI tools to external services meant stitching together individual APIs. Want your AI agent to create a Linear issue from a bug report and then open a PR in GitHub? That's two different APIs, two different auth flows, two different SDKs, two different error handling patterns. And that's just two services. A real workflow might touch five or six.

For documentation specifically, the options were even rougher:

  1. Copy-paste. Grab the relevant docs, paste them into the chat window. Works for one-off questions. Falls apart the moment you need context across multiple pages or want anything automated.
  2. Dump the whole thing. Point Claude Code at your llms.txt or tell Cursor to fetch your docs site with @web. You get the content, but it's a firehose. No structure, no search, no way for the AI to pull just the specific page it needs. Token limits become a problem fast.
  3. Hope the training data is good enough. The AI might have seen your docs during training. Or it might have seen a two-year-old version. Or a blog post that paraphrases them incorrectly. You don't know, and neither does the user.

Every service is a different integration. Every integration is a different API to learn, authenticate against, and maintain. None of them give AI tools structured, on-demand access. They're all workarounds.

MCP replaces this with a single protocol. Linear exposes an MCP server. GitHub exposes an MCP server. Your documentation exposes an MCP server. The AI client connects to all of them the same way. Same handshake, same message format, same tool discovery. You build the server once, and every MCP-compatible client can use it: Cursor, VS Code with Copilot, Claude Desktop, Claude Code, Windsurf, Zed.

The protocol itself is open source, governed as a Series of LF Projects under the Linux Foundation, and already has SDKs for TypeScript, Python, Java, Kotlin, C#, Swift, and Go.

How MCP Actually Works

MCP follows a client-server architecture. The key participants:

  • MCP Host: The AI application (Claude Desktop, Cursor, VS Code). It's the thing the user interacts with.
  • MCP Client: A component inside the host that maintains a connection to one MCP server. One host can have many clients, each connected to a different server.
  • MCP Server: A program that exposes data and tools to MCP clients. This is what you build.

The protocol sits on two layers:

Transport Layer: How messages physically move between client and server. MCP supports two transports:

  • Stdio: Standard input/output. The client spawns the server as a child process. Great for local tools. Zero network overhead. This is what you use when you npx a server from your terminal config.
  • Streamable HTTP: HTTP POST for requests, with optional Server-Sent Events (SSE) for streaming. This is what you use for remote servers, the kind that run on the internet and serve many clients. It supports standard HTTP auth (bearer tokens, API keys, OAuth).

Data Layer: What the messages actually contain. MCP uses JSON-RPC 2.0, the same spec that LSP (Language Server Protocol) uses. If you've ever worked on editor tooling, this will feel familiar.

The Handshake

Every MCP connection starts with an initialization handshake. The client sends an initialize request:

The server responds with its capabilities, what primitives it supports:

This is capability negotiation. The client learns what the server can do. The server learns what the client supports. Both sides agree on a protocol version.

The Three Primitives

MCP servers expose three types of things:

Tools are functions the AI can call. "Search the docs." "Get a page." "Run a query." The AI decides when to invoke them based on the conversation. Tools are the most commonly used primitive.

Resources are data the AI can read, like files or endpoints that provide context. The client requests them; they don't execute logic.

Prompts are reusable templates for structuring AI interactions. Less common in practice.

Tool Discovery and Execution

After initialization, the client asks what tools are available:

The server responds with metadata about each tool, including a JSON Schema for the inputs:

This tool metadata gets injected into the AI's context. When a user asks "how do I authenticate?", the AI sees the search_docs tool, decides to call it with {"query": "authentication"}, and the result gets fed back into the conversation. The user never sees the JSON-RPC messages. Initialize, discover tools, call tools as needed. The power comes from the standardization.

Why This Matters for Documentation

Documentation is context. It's the thing AI agents need to do their jobs well. Without it, they hallucinate. With it, they're actually useful.

But here's the problem: most documentation lives behind JavaScript-heavy websites that AI tools can't easily scrape. Even if they can reach it, they get raw HTML mixed with nav chrome, ad scripts, and cookie banners. The signal-to-noise ratio is terrible.

MCP flips this. Instead of AI tools scraping your docs site and hoping for the best, you serve them structured, clean data through a protocol they understand. A developer using Cursor can say "explain how to set up webhooks according to our docs" and Cursor will search your documentation MCP server, read the relevant pages, and give an accurate answer. No copy-pasting. No hallucination. No stale training data.

Security: The Part Nobody Wants to Talk About

MCP is powerful precisely because it gives AI agents access to external systems. That power comes with real risks. Security researchers have already demonstrated attacks that should make you cautious about which MCP servers you connect to.

Tool Poisoning Attacks

This is the big one. Invariant Labs discovered that malicious instructions can be embedded in MCP tool descriptions, invisible to users but visible to the AI model.

Here's a simplified example of a poisoned tool:

Looks like a simple addition tool. But the hidden instructions in the description tell the AI to read sensitive files (SSH keys, MCP credentials) and exfiltrate them through the sidenote parameter. The user sees "add two numbers" in the UI. The AI model sees the full description and follows the malicious instructions.

Invariant demonstrated this working against Cursor. The AI willingly read the user's ~/.cursor/mcp.json and SSH keys, then sent them to the malicious server. The tool call confirmation dialog didn't show the actual data being exfiltrated because the UI truncated the arguments.

Practical Takeaways

  1. Only connect to MCP servers you trust. This sounds obvious, but the npm-like ecosystem emerging around MCP makes it easy to install random servers. Treat them with the same caution you'd give a random npm package.
  2. Prefer remote servers hosted by the service provider. A remote MCP server hosted by the documentation maintainer runs in their infrastructure, not yours. It can't read your filesystem. It can't access your SSH keys. The blast radius of a compromise is constrained to the data the server is designed to serve.
  3. Review tool descriptions. Before connecting a local MCP server, inspect the project's tool registrations. Look for hidden instructions in descriptions. Tools like mcp-scan from Invariant can automate this.
  4. Pin versions. If you're using a local MCP server, pin the exact version in your config. Don't let it auto-update without review.
  5. Watch for excessive permissions. A documentation-only MCP server shouldn't need to read your filesystem or make arbitrary network requests. If a tool's input schema has suspiciously broad parameters, that's a red flag.

Remote vs. Local: The Deployment Decision

MCP servers come in two flavors, and the choice matters:

Local (Stdio) servers run on your machine. The AI client spawns them as child processes. They're fast (no network round-trip), but they run with your user's full permissions. Every npx @somepackage/mcp-server in your Cursor config is code running on your machine with access to your files, environment variables, and network.

Remote (Streamable HTTP) servers run on the internet. The AI client connects to them over HTTPS. They're slightly slower (network latency), but they're sandboxed. They can only access the data they're designed to serve. They can't read your .ssh directory or your mcp.json credentials file.

For documentation, remote servers are the obvious choice. Documentation is public data. There's no reason to run it locally. A remote server:

  • Can't access the user's filesystem
  • Runs in the provider's infrastructure with defined boundaries
  • Serves many clients simultaneously
  • Can be rate-limited, monitored, and updated without touching client configs

The setup is also simpler. Instead of installing packages, users just add a URL:

No npx. No node_modules. No supply chain to worry about.

What This Looks Like in Practice

At Docsalot, we've been building hosted MCP servers for documentation sites. Every site published through our platform automatically gets an MCP endpoint.

The server exposes three tools:

  • search_docs: Full-text search across all documentation pages, returning ranked results with snippets.
  • list_pages: Returns every page with its path, title, and description.
  • get_page: Returns the complete markdown content of any page, including frontmatter.

Connecting to a Docsalot MCP server from any client is a one-line config:

Because these are remote HTTP servers, there's no local code execution. The server only has access to the documentation data it's designed to serve.

We also added one-click install buttons on every documentation page: Connect to Cursor, Connect to VS Code, Connect to Claude Code. Users don't even need to edit config files manually.

Where MCP Is Headed

MCP is evolving fast. The protocol went from spec to widespread adoption in under a year. A few things to watch:

OAuth integration is being formalized. The current spec includes a full authorization flow for remote servers, which means MCP servers will be able to serve user-specific data (private repos, team docs, internal APIs) with proper access control.

The ecosystem is exploding. There are already MCP servers for Sentry, GitHub, Postgres, Slack, and dozens of other services. The network effects are real: the more servers exist, the more clients implement support, which incentivizes more servers.

The Bottom Line

MCP is the first serious attempt at standardizing how AI agents access external context. It's not perfect. The security model has real gaps, the ecosystem is young, and the spec is still evolving. But the alternative (every AI tool building bespoke integrations) is clearly worse.

If you're building developer tools or maintaining documentation, this is worth paying attention to now. The developers using your product are already using AI tools. The question isn't whether those tools will try to access your docs. They already are, by scraping your site. The question is whether you'll serve them structured, accurate content through a standard protocol, or leave them to hallucinate from whatever they can scrape.

References