Concept

MCP protocol basics

The Model Context Protocol is a JSON-RPC dialect for AI clients to discover and invoke tools. Lumin speaks it over Streamable HTTP.

What MCP is

MCP is an open standard (governed by the Linux Foundation's Agentic AI Foundation as of 2026) for exposing tools to AI clients. Servers publish a tool list with schemas; clients call them by name with structured arguments. The protocol layer is JSON-RPC 2.0, the transport is HTTP or Streamable HTTP.

Three primitives

Tools. Callable functions with structured input/output. Lumin exposes 221 of these: 218 engine-backed, plus 3 meta-tools that carry the reading protocol and the tool taxonomy.
Resources. Readable content (files, snapshots). Not used by Lumin yet.
Prompts. Pre-built prompt templates. Not used by Lumin.

The two methods you will use

tools/list returns the complete tool catalog with input schemas. Call it once after connecting to populate your client.

tools/call invokes a tool by name with arguments. Returns a content array (text and structured) on success, or an error object.

Instructions, and why they cannot be trusted

A server also publishes an instructions string in its initialize response, which the client is meant to fold into the model's system prompt. The spec sets no length limit and clients set their own. Lumin's reading protocol runs to roughly 32,000 characters, and one major client was measured delivering the first 2,000 of them, about 6 percent.

So Lumin treats instructions as best-effort. The load-bearing rules, the tool-call floors and the order of work, sit in the first 1,633 characters where truncation cannot reach them. The full reference follows for clients that deliver the string whole. And the same content is available as a tool result, which no client truncates: get_reading_protocol returns it on demand.

If you are writing your own client, this is the general lesson rather than a Lumin quirk. Never put a rule only in instructions if the model must obey it. See reading depth and call floors and the meta-tools reference.

The transport is Streamable HTTP, and the wire is SSE

Every response to a POST /mcp request is a Server-Sent-Events stream, not a plain JSON body. A successful call comes back as one or more data: lines carrying the JSON-RPC payload, which is why a request needs Accept: application/json, text/event-stream (both, on every call) or the server answers 406, and why a raw curl | jq pipe fails until the data: prefix is stripped first. See quickstart for the working curl idiom.

One handler serves both protocol revisions the MCP spec has had in this era: 2025-11-25 and 2026-07-28. A 2025-11-25 client still gets the familiar initialize handshake. A 2026-07-28 client gets the newer stateless wire instead: the protocol version, client info and capabilities ride in _meta on every request, there is no Mcp-Session-Id header, and there is no session state on the server between calls, which matches Lumin's birth data model, every call already carries its own birth fields rather than relying on anything set earlier in the conversation. Clients negotiate whichever revision they speak, so nothing about this changes on a fixed date for anyone.