MCP protocol primer
Learn the MCP concepts developers need before building with MCP Stack.
MCP, the Model Context Protocol, is a JSON-RPC based protocol that lets clients and servers exchange tools, resources, prompts, and other capabilities. The official MCP specification describes the base protocol, lifecycle, authorization, transports, server features, and client features.
Useful official references:
MCP messages are JSON-RPC 2.0 messages. Clients and servers exchange requests, responses, errors, and notifications. The lifecycle starts with initialize, where the client and server negotiate protocol version and capabilities.
For developers using MCP Stack, the key point is simple: your generated MCP server needs to expose a valid MCP surface, and the client or agent will discover capabilities through normal MCP messages.
MCP defines two standard transport mechanisms: stdio and Streamable HTTP. MCP Stack's production surfaces are built around Streamable HTTP because hosted and external clients need a network endpoint.
A Streamable HTTP MCP server exposes a single endpoint path, commonly:
https://mcp.example.com/mcpThat endpoint handles MCP JSON-RPC messages and may use Server-Sent Events for streaming server messages.
The MCP transport specification calls out Origin validation, localhost binding for local servers, and authentication for HTTP connections. MCP Stack Gateway and Host exist because production MCP endpoints need more than a raw local server.
Tools are model-callable functions exposed by an MCP server. A tool has a name, description, input schema, and optionally output schema, annotations, and execution metadata.
In MCP Stack, OpenAPI operations become tools. The dashboard lets you:
Tool quality matters because the model chooses from descriptions and schemas. A vague tool description leads to vague agent behavior.
MCP prompts are reusable prompt templates exposed by a server. The MCP spec frames prompts as user-controlled, meaning clients can surface them as selectable commands or templates.
In MCP Stack, prompts are useful for stable domain context:
Prompts should not replace tool-specific instructions. Use prompts for broad context and use tool instructions for endpoint behavior.
Resources let servers expose contextual data, such as files, database schemas, or application-specific information, identified by URI. The official MCP spec describes resources as application-driven: the host application decides how to incorporate them.
Generated OpenAPI MCP servers mainly focus on tools. Resources become important when your product needs contextual knowledge beyond tool calls, such as schemas, documents, or project files.
MCP Stack maps normal SaaS API concepts into MCP concepts:
| Product concept | MCP concept | MCP Stack surface |
|---|---|---|
| OpenAPI operation | Tool | Select Tools, Tools tab |
| Endpoint-specific agent guidance | Tool description and instructions | Tool instructions editor |
| Product-wide agent guidance | Prompt or system prompt | AI Prompts, Agent configuration |
| Public network endpoint | Streamable HTTP transport | Hosted MCP URL |
| User login and API authorization | OAuth for HTTP MCP | Gateway |
| Operational checks | JSON-RPC smoke tests | Runtime checks, tools/list smoke |
You do not need to become an MCP spec expert to use MCP Stack, but you should understand:
In one sentence:
MCP is a JSON-RPC protocol that lets AI clients discover and call tools exposed by a server. MCP Stack turns your OpenAPI operations into MCP tools, gives them a production HTTP endpoint, and adds Gateway when OAuth and client discovery are required.
From here, decide whether you are generating a server, connecting a client, configuring OAuth, or embedding an agent.