# Model Context Protocol for Developers: Servers, Clients and Security

> The Model Context Protocol is an open JSON-RPC protocol: an MCP server exposes tools, resources and prompts that any compatible agent host can use. Build an integration once, run it locally over stdio or remotely over Streamable HTTP with OAuth, and reuse it from Claude, the OpenAI Agents SDK, LangChain or CrewAI.

Canonical URL: https://www.ruebstudio.de/en/guides/agent-frameworks/model-context-protocol-developer-guide  
Author: Dr.-Ing. Marcus Rüb, CEO  
Published: 2026-11-01

Teams that connect AI agents to internal systems tend to write the same integration several times: once as a Claude tool, once for the OpenAI Agents SDK, once for LangChain. The Model Context Protocol (MCP) moves that integration down to the protocol layer. This guide is for developers and IT leads who need to understand how MCP actually works, how to build a server, and what the security model expects of them. It reflects the specification as of November 2026, revision 2026-07-28.

## What is MCP, and what problem does it solve?

MCP is an open protocol that defines how an AI application talks to external data sources and tools. An MCP server exposes capabilities; any MCP-capable client can use them. Your connection to a CRM, ticketing system or document store becomes a reusable service rather than code tied to one agent framework.

The [specification](https://modelcontextprotocol.io/specification/latest) names the Language Server Protocol as its model. LSP let one language server work across many editors; MCP aims to let one integration work across many AI applications.

For a short, non-technical definition, see the glossary entry [What Is Model Context Protocol (MCP)?](https://www.ruebstudio.de/en/glossary/model-context-protocol-mcp). This guide goes further: message flow, transports, building and testing a server, and the authorization rules you are expected to implement. If your question is how to connect MCP servers to SAP, Microsoft 365 or a CRM and run them in a company setting, read [MCP Servers: Connecting AI Agents to Systems the Standard Way](https://www.ruebstudio.de/en/guides/ai-agent-integrations/mcp-servers-connect-ai-agents) instead. That guide takes the systems view; this one takes the protocol and framework view.

Common reasons to build an MCP server:

- **Read access to business data:** an agent looks up product records, open support tickets or delivery notes.
- **Write actions:** an agent drafts a quotation or comments on a ticket, ideally after a human confirms.
- **Developer tooling:** coding agents reach issue trackers, databases or internal docs.
- **A shared layer for several agents:** sales, support and knowledge agents use the same server for the same backend.

## How does MCP work under the hood?

MCP exchanges JSON-RPC 2.0 messages between three roles: host, client and server. The host is the AI application, the client is the connector inside it, and the server provides capabilities. Since revision 2026-07-28 the protocol is stateless, so every request carries its own protocol version and client capabilities.

### Roles

According to the [specification](https://modelcontextprotocol.io/specification/latest):

- **Host:** the application that opens connections, such as a chat app, an IDE or your own agent runtime.
- **Client:** the connector inside the host that talks to one server.
- **Server:** the service that provides context and capabilities.

### Server primitives

A server can offer three kinds of capability:

- **Tools** are functions the model calls. Clients discover them with `tools/list` and invoke them with `tools/call`. Inputs are described by a JSON Schema (`inputSchema`); outputs can be described too (`outputSchema`, returned as `structuredContent`).
- **Resources** are context and data, such as a file or a record, addressed by URI.
- **Prompts** are templated messages and workflows that a user selects.

The spec calls tools "model-controlled": the model decides when to call them. Resources and prompts are typically driven by the application or the user.

### What changed in revision 2026-07-28

Older tutorials describe mechanisms that no longer exist in the current revision. The [changelog](https://modelcontextprotocol.io/specification/2026-07-28/changelog) lists, among others:

- The `initialize` handshake is gone. Each request carries the protocol version and client capabilities in `_meta`.
- Servers must implement `server/discover`, which clients can call up front to check versions and capabilities.
- Protocol-level sessions and the `Mcp-Session-Id` header were removed. A server that needs state across calls returns its own handle, which the model passes back as an ordinary tool argument.
- Servers no longer send their own requests to clients. When a server needs more input, it returns an `InputRequiredResult`, and the client retries the original request with the answers (the Multi Round-Trip Requests pattern).
- Roots, Sampling and Logging are deprecated; new implementations should not add them.
- Tasks for long-running work moved out of the core into an official extension.

In practice, a modern MCP server behaves much like a stateless HTTP API. That suits load balancers and horizontally scaled deployments, because no session is pinned to one instance.

## stdio or Streamable HTTP: which transport should you use?

The spec defines two standard transports. With stdio, the client starts the server as a subprocess and exchanges newline-delimited JSON-RPC over standard input and output. With Streamable HTTP, the server runs as its own service behind a single HTTP endpoint. Use stdio for local tools and Streamable HTTP for shared or remote servers.

### stdio

stdio fits tools that run on the user's machine, such as access to a local repository. Only the launching client can reach the server, and credentials come from environment variables. The [Security Best Practices](https://modelcontextprotocol.io/specification/latest/basic/security_best_practices) recommend stdio for locally run servers for exactly that reason.

### Streamable HTTP

For servers that serve several users or agents, Streamable HTTP is the standard. The [transport specification](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http) sets out the shape:

- One MCP endpoint, for example `https://example.com/mcp`, that accepts POST.
- Each message is its own POST. The reply is a single JSON object or a Server-Sent Events stream scoped to that one request.
- Every request carries `MCP-Protocol-Version` and `Mcp-Method`, plus `Mcp-Name` for tool calls, so gateways can route without parsing the body. Servers must reject requests where headers and body disagree.
- Clients subscribe to change notifications, such as an updated tool list, through `subscriptions/listen`.

Streamable HTTP arrived with protocol version 2025-03-26, replacing the HTTP+SSE transport from 2024-11-05, which is now formally deprecated. New servers should not offer it.

## Why one MCP server works across agent frameworks

MCP's main payoff is reuse. A server you build once can be attached to Claude, the OpenAI Agents SDK, LangChain and CrewAI through each framework's own MCP client, so integration logic lives in one place. The frameworks differ in which transports and which primitives they support, and that shapes how you design the server.

How each client consumes MCP, based on its documentation (checked November 2026):

| Client | How you attach a server | Transports | Note |
|---|---|---|---|
| Claude Code | `claude mcp add` | stdio, HTTP | SSE marked deprecated |
| Claude API | MCP connector (beta) | public HTTP only | tool calls only |
| OpenAI Agents SDK | `MCPServerStdio`, `MCPServerStreamableHttp`, `HostedMCPTool` | stdio, Streamable HTTP | tool filters, approvals |
| LangChain | `MCPAdapter` from `langchain.mcp` | stdio, Streamable HTTP | `langchain[mcp]` 1.4.0+, beta |
| CrewAI | `mcps` field on an agent, `MCPServerAdapter` | stdio, SSE, Streamable HTTP | mainly tools |

Details that matter when you design a server:

- **Claude Code** stores servers in `local`, `project` or `user` scope. Project-scoped servers live in a `.mcp.json` file you can commit, and the [Claude Code docs](https://code.claude.com/docs/en/mcp) say it asks for approval before using them in interactive sessions.
- The **Claude API MCP connector** reaches remote servers straight from the Messages API without your own client. Its [documentation](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector) states that only tool calls are supported and the server must be publicly reachable over HTTP.
- The **OpenAI Agents SDK** [documents](https://openai.github.io/openai-agents-python/mcp/) static and dynamic tool filters plus `require_approval` for per-tool human sign-off. With `HostedMCPTool`, the Responses API calls the remote server on the model's behalf.
- **LangChain** moved MCP support into `langchain.mcp` in version 1.4.0; the older `langchain-mcp-adapters` package is, per the [LangChain docs](https://docs.langchain.com/oss/python/langchain/mcp), the pre-1.4.0 route.
- **CrewAI** [notes](https://docs.crewai.com/en/mcp/overview) that its adapter primarily supports tools; prompts and resources are not mapped to CrewAI components.

For choosing a framework in the first place, see the [comparison of AI agent frameworks](https://www.ruebstudio.de/en/guides/agent-frameworks/ai-agent-frameworks-comparison); for MCP, what matters is that all five can share one server.

The design rule that follows: anything an agent must be able to do belongs in a tool. Resources and prompts are useful extras for clients that support them, not a lowest common denominator you can rely on. For business agents in areas such as [sales](https://www.ruebstudio.de/en/ai-agents/sales) or [technical service](https://www.ruebstudio.de/en/ai-agents/technical-service), a well-scoped MCP server becomes the integration layer several agents share.

## What do you need before building an MCP server?

You need a backend with a stable interface, a clear list of permitted actions and an access model. On the technical side, an official SDK and a runtime are enough to start. On the organisational side, someone must own the server, decide which tools need approval and review the access logs.

**Technical prerequisites:**

- An API, database or file store the server may access, using a service account or delegated user rights.
- An official SDK. The [SDK overview](https://modelcontextprotocol.io/docs/sdk) lists TypeScript, Python, C#, Go, Rust and Ruby as Tier 1, Java as Tier 2, and Swift, PHP and Kotlin as Tier 3. Each SDK adopts new protocol revisions on its own schedule, so check which revision yours supports.
- For remote servers: HTTPS, an identity provider that speaks OAuth 2.1, and a hosting environment with logging.

**Organisational prerequisites:**

- A named business owner per server who decides which actions are allowed.
- A rule for which tools always require human confirmation.
- An allowlist of third-party MCP servers people may connect.

## How do you build an MCP server, step by step?

Start with a small read-only server exposing two or three tools, test it locally over stdio, then add write actions, the HTTP transport and authorization. Tool design matters more than anything else: a few precisely named, well-described actions beat one generic query tool that leaves the model too much room.

### Step 1: Define the actions

List the questions and actions the agent needs, such as "fetch open tickets for an account" or "create a draft quotation". Each becomes a tool with a descriptive name. The [tools specification](https://modelcontextprotocol.io/specification/2026-07-28/server/tools) recommends names of 1 to 128 characters using letters, digits, underscore, hyphen and dot. A generic `run_sql` tool is convenient for you but hands the model far more power than the task needs.

### Step 2: Scaffold the server with an SDK

The Python SDK (package `mcp`, version 2.3.0 on PyPI as of November 2026) shows a minimal server using the `MCPServer` class in its [README](https://github.com/modelcontextprotocol/python-sdk):

```python
from mcp.server import MCPServer

mcp = MCPServer("Demo")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b

@mcp.resource("greeting://{name}")
def greeting(name: str) -> str:
    """Greet someone by name."""
    return f"Hello, {name}!"
```

You do not write a separate JSON Schema: as the README puts it, the type hints `a: int, b: int` are the schema. Still write the docstring with care, because the tool description is what the model reads when deciding whether and how to call it.

### Step 3: Test locally

The README gives commands for the MCP Inspector and for serving over Streamable HTTP:

```bash
pip install "mcp[cli]"
uv run mcp dev server.py
uv run mcp run server.py --transport streamable-http
```

Then attach the server to a real client, for example Claude Code with `claude mcp add --transport http <name> <url>`, using your local endpoint's URL.

### Step 4: Return errors the model can use

The spec separates two error types. Protocol errors, such as an unknown tool or a malformed request, are JSON-RPC errors. Business errors, such as a date in the past, are returned as a normal result with `isError: true` and a message that lets the model correct its call and retry.

### Step 5: Model state with handles

If a workflow needs state across steps, such as a basket or a multi-step draft, have a tool return a random, unguessable handle that later calls pass back. Check on every call that the caller is authorised for that handle.

### Step 6: Authorization and operations

For remote deployment, add OAuth (next section), rate limits, a log entry for every tool call and a deterministic order in `tools/list`, which the spec recommends to help client-side caching.

## How do you secure an MCP server?

Treat every tool call as untrusted input acting on your systems. The specification requires servers to validate inputs, enforce access control, rate-limit calls and sanitise outputs. Remote servers use OAuth 2.1, and they may only accept tokens issued specifically for them.

### Authorization for HTTP servers

The [authorization specification](https://modelcontextprotocol.io/specification/latest/basic/authorization) targets HTTP transports; stdio servers should not follow it and should read credentials from the environment instead. The key obligations:

- The MCP server is an OAuth 2.1 resource server and must publish Protected Resource Metadata (RFC 9728) so clients can discover its authorization server.
- Clients must send Resource Indicators (RFC 8707), naming the specific MCP server the token is for.
- Servers must check that a token was issued for them as the audience, and must not accept or pass through any other token.
- Tokens go in the `Authorization` header, never in the query string.
- Client ID Metadata Documents are the preferred registration method; Dynamic Client Registration is deprecated as of 2026-07-28.

### Attacks to design against

The [Security Best Practices](https://modelcontextprotocol.io/specification/latest/basic/security_best_practices) cover, among others:

- **Token passthrough:** forwarding a client's token unchecked to a downstream API bypasses controls and breaks the audit trail. Accept only tokens issued to your server.
- **Confused deputy:** proxy servers that use one static client ID with a third-party API can be abused unless they show their own per-client consent screen.
- **State handle hijacking:** guessing a handle must never grant access to another user's data. Bind handles to the authenticated user.
- **SSRF:** a malicious server can point clients at internal addresses through OAuth metadata URLs. Clients should enforce HTTPS and block private address ranges.
- **Local server compromise:** a startup command in a client config is executable code. Clients that offer one-click setup must show the full command and ask for explicit approval first.
- **Over-broad scopes:** start with minimal scopes and request more only when an operation needs them.

For local HTTP servers, the transport spec adds two rules: validate the `Origin` header to block DNS rebinding, and bind to `127.0.0.1` rather than every interface.

### Treat tool metadata as untrusted

The spec says clients must treat tool annotations as untrusted unless they come from a trusted server, and that a human should always be able to deny a tool call. In practice: only allow vetted servers, require confirmation for write tools, and assume that content a server fetches from the web may carry [prompt injection](https://www.ruebstudio.de/en/glossary/prompt-injection), a risk the Claude Code documentation also flags.

## Limits and risks of MCP

MCP standardises the connection, not the quality of what sits behind it. Poorly designed tools, missing permissions or an unreliable backend stay problems whatever protocol carries them. The specification also moves quickly, and clients differ in what they support.

- **A moving specification:** revision 2026-07-28 removed the handshake, sessions and server-initiated requests. Servers built against 2025-11-25 need backward compatibility or a migration. Budget for regular updates.
- **Uneven client support:** not every client handles resources, prompts or user input requests. Test each target client separately.
- **Context cost:** every exposed tool lands in the model's context with its description. Many servers with many tools make selection worse and runs more expensive. Tool filters, such as those in the OpenAI Agents SDK, help.
- **When MCP is overkill:** a single function used by one agent in one framework is simpler as a native tool. MCP pays off once several agents or frameworks need the same integration.
- **Operations:** a remote server is a production service with monitoring, patching and access logs, not a script you start once.

## How should you get started?

Start with one read-only server for a system several agents need, attach it to two different clients locally and compare how each behaves. Add write actions, HTTP hosting and OAuth only once the tool design and descriptions hold up.

A practical sequence:

1. **Pick one backend** that matters to several use cases, such as the document store or the ticketing system.
2. **Build three read-only tools** and exercise them in the MCP Inspector.
3. **Attach the server to two clients**, for example Claude Code and an agent built with the OpenAI Agents SDK, to confirm the reuse works.
4. **Add write tools behind confirmation** and log every call.
5. **Move to Streamable HTTP**, configure OAuth 2.1 with your identity provider and keep scopes narrow.
6. **Follow the specification changelog** and update SDK versions on a schedule.

A useful rule of thumb: scope MCP servers by backend system, not by agent. One server per system, shared by every agent, stays maintainable; one server per agent duplicates logic. For how such integrations turn into business-specific agents, see the overview of [AI agents for companies](https://www.ruebstudio.de/en/ai-agents).

## Frequently asked questions

### Which version of the MCP specification is current?

As of November 2026 the current revision is 2026-07-28. It made the protocol stateless by removing the initialize handshake and protocol-level sessions.

### Does every MCP server need OAuth?

No. Local stdio servers take credentials from the environment. Remote HTTP servers that protect data should follow the OAuth 2.1-based authorization spec, acting as a resource server.

### Can the Claude API connect to my local stdio server?

Not directly. The Messages API MCP connector only reaches servers exposed publicly over HTTP, so local stdio servers need your own MCP client or a host such as Claude Code.

### Do all clients support resources and prompts?

No. The Claude API connector and CrewAI's adapter document tool support as their main focus. Anything every agent must be able to do belongs in a tool.

### Which language should I build my server in?

Use your team's language. TypeScript, Python, C#, Go, Rust and Ruby have Tier 1 official SDKs, and Java is Tier 2.

## Sources

- [Model Context Protocol – Specification (revision 2026-07-28)](https://modelcontextprotocol.io/specification/latest)
- [MCP Specification – Key Changes 2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28/changelog)
- [MCP Specification – Streamable HTTP](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http)
- [MCP Specification – Authorization](https://modelcontextprotocol.io/specification/latest/basic/authorization)
- [MCP – Security Best Practices](https://modelcontextprotocol.io/specification/latest/basic/security_best_practices)
- [MCP Specification – Tools](https://modelcontextprotocol.io/specification/2026-07-28/server/tools)
- [MCP – Official SDKs](https://modelcontextprotocol.io/docs/sdk)
- [MCP Python SDK (GitHub)](https://github.com/modelcontextprotocol/python-sdk)
- [Claude Code – Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp)
- [Claude API – MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector)
- [OpenAI Agents SDK – Model Context Protocol](https://openai.github.io/openai-agents-python/mcp/)
- [LangChain – Model Context Protocol](https://docs.langchain.com/oss/python/langchain/mcp)
- [CrewAI – MCP Servers as Tools](https://docs.crewai.com/en/mcp/overview)
