MCP

Helpers for building Model Context Protocol (MCP) envelopes. More...

Classes
struct	sourcemeta::core::MCPToolAnnotations
struct	sourcemeta::core::MCPImplementation
struct	sourcemeta::core::MCPServerCapabilities

Enumerations
enum class	sourcemeta::core::MCPProtocolVersion : std::uint8_t { MCPProtocolVersion::V_2025_03_26 , MCPProtocolVersion::V_2025_06_18 , MCPProtocolVersion::V_2025_11_25 }

Functions
constexpr auto	sourcemeta::core::mcp_protocol_version_string (const MCPProtocolVersion version) noexcept -> JSON::StringView
constexpr auto	sourcemeta::core::mcp_is_request_method (const JSON::StringView method) noexcept -> bool
constexpr auto	sourcemeta::core::mcp_resolve_protocol_version (const JSON::StringView header) noexcept -> std::optional< MCPProtocolVersion >
constexpr auto	sourcemeta::core::mcp_supports_output_schema (const MCPProtocolVersion version) noexcept -> bool
constexpr auto	sourcemeta::core::mcp_supports_structured_content (const MCPProtocolVersion version) noexcept -> bool
constexpr auto	sourcemeta::core::mcp_supports_resource_link_content (const MCPProtocolVersion version) noexcept -> bool
constexpr auto	sourcemeta::core::mcp_supports_implementation_title (const MCPProtocolVersion version) noexcept -> bool
constexpr auto	sourcemeta::core::mcp_supports_implementation_description (const MCPProtocolVersion version) noexcept -> bool
constexpr auto	sourcemeta::core::mcp_supports_implementation_website_url (const MCPProtocolVersion version) noexcept -> bool
constexpr auto	sourcemeta::core::mcp_supports_jsonrpc_batching (const MCPProtocolVersion version) noexcept -> bool
SOURCEMETA_CORE_MCP_EXPORT auto	sourcemeta::core::mcp_make_text_block (const JSON::StringView text) -> sourcemeta::core::JSON
SOURCEMETA_CORE_MCP_EXPORT auto	sourcemeta::core::mcp_make_resource_link (const MCPProtocolVersion version, const JSON::StringView uri, const JSON::StringView mime_type, const JSON::StringView name={}, const JSON::StringView description={}) -> sourcemeta::core::JSON
SOURCEMETA_CORE_MCP_EXPORT auto	sourcemeta::core::mcp_make_tool_success (const MCPProtocolVersion version, const sourcemeta::core::JSON &identifier, sourcemeta::core::JSON result) -> sourcemeta::core::JSON
SOURCEMETA_CORE_MCP_EXPORT auto	sourcemeta::core::mcp_make_tool_success (const MCPProtocolVersion version, const sourcemeta::core::JSON &identifier, sourcemeta::core::JSON structured, sourcemeta::core::JSON content_blocks) -> sourcemeta::core::JSON
SOURCEMETA_CORE_MCP_EXPORT auto	sourcemeta::core::mcp_make_tool_error (const sourcemeta::core::JSON &identifier, const JSON::StringView message) -> sourcemeta::core::JSON
SOURCEMETA_CORE_MCP_EXPORT auto	sourcemeta::core::mcp_make_error_resource_not_found (const sourcemeta::core::JSON &identifier) -> sourcemeta::core::JSON
SOURCEMETA_CORE_MCP_EXPORT auto	sourcemeta::core::mcp_make_resource (const JSON::StringView uri, const JSON::StringView name, const JSON::StringView mime_type, const JSON::StringView description={}, const std::optional< std::size_t > size=std::nullopt, const std::optional< double > priority=std::nullopt) -> sourcemeta::core::JSON
SOURCEMETA_CORE_MCP_EXPORT auto	sourcemeta::core::mcp_make_resource_text_content (const JSON::StringView uri, const JSON::StringView mime_type, const JSON::StringView text) -> sourcemeta::core::JSON
SOURCEMETA_CORE_MCP_EXPORT auto	sourcemeta::core::mcp_make_resources_read_result (sourcemeta::core::JSON contents) -> sourcemeta::core::JSON
SOURCEMETA_CORE_MCP_EXPORT auto	sourcemeta::core::mcp_make_resource_template (const JSON::StringView uri_template, const JSON::StringView name, const JSON::StringView description, const JSON::StringView mime_type) -> sourcemeta::core::JSON
SOURCEMETA_CORE_MCP_EXPORT auto	sourcemeta::core::mcp_make_tool_descriptor (const MCPProtocolVersion version, const JSON::StringView name, const JSON::StringView description, sourcemeta::core::JSON input_schema, std::optional< sourcemeta::core::JSON > output_schema=std::nullopt, const MCPToolAnnotations &annotations={}) -> sourcemeta::core::JSON
SOURCEMETA_CORE_MCP_EXPORT auto	sourcemeta::core::mcp_make_initialize_result (const sourcemeta::core::JSON &request, const MCPServerCapabilities &capabilities, const MCPImplementation &server, const JSON::StringView instructions={}) -> sourcemeta::core::JSON
SOURCEMETA_CORE_MCP_EXPORT auto	sourcemeta::core::mcp_tool_call_arguments (const sourcemeta::core::JSON &envelope) -> const sourcemeta::core::JSON *

Variables
constexpr JSON::StringView	sourcemeta::core::MCP_METHOD_INITIALIZE {"initialize"}
constexpr JSON::StringView	sourcemeta::core::MCP_METHOD_PING {"ping"}
constexpr JSON::StringView	sourcemeta::core::MCP_METHOD_TOOLS_LIST {"tools/list"}
constexpr JSON::StringView	sourcemeta::core::MCP_METHOD_TOOLS_CALL {"tools/call"}
constexpr JSON::StringView	sourcemeta::core::MCP_METHOD_RESOURCES_LIST {"resources/list"}
constexpr JSON::StringView	sourcemeta::core::MCP_METHOD_RESOURCES_READ {"resources/read"}
constexpr JSON::StringView	sourcemeta::core::MCP_METHOD_RESOURCES_TEMPLATES_LIST
constexpr JSON::StringView	sourcemeta::core::MCP_METHOD_NOTIFICATIONS_INITIALIZED
constexpr std::int64_t	sourcemeta::core::MCP_CODE_RESOURCE_NOT_FOUND {-32002}
constexpr std::int64_t	sourcemeta::core::MCP_CODE_URL_ELICITATION_REQUIRED {-32042}

Detailed Description

Helpers for building Model Context Protocol (MCP) envelopes.

This functionality is included as follows:

#include <sourcemeta/core/mcp.h>

---

Class Documentation

sourcemeta::core::MCPToolAnnotations

struct sourcemeta::core::MCPToolAnnotations

Optional hints attached to an MCP tool descriptor.

Public Attributes
JSON::StringView	title = {}
	Optional human-readable title for the tool.
bool	read_only = false
	true when the tool guarantees no side effects.
bool	destructive = true
	true when the tool may mutate or delete state.
bool	idempotent = false
bool	open_world = true
	true when the tool interacts with state outside the server's control.

Member Data Documentation

idempotent

bool sourcemeta::core::MCPToolAnnotations::idempotent = false

true when repeated invocations with the same input yield the same result.

sourcemeta::core::MCPImplementation

struct sourcemeta::core::MCPImplementation

Implementation info advertised by an MCP server during the initialize handshake.

Public Attributes
JSON::StringView	name
	Short machine-readable server name.
JSON::StringView	version
	Semver-compatible server version.
JSON::StringView	title = {}
	Optional human-readable title.
JSON::StringView	description = {}
	Optional human-readable description.
JSON::StringView	website_url = {}
	Optional public website URL.

sourcemeta::core::MCPServerCapabilities

struct sourcemeta::core::MCPServerCapabilities

Boolean toggles for the MCP capabilities object returned during the initialize handshake.

Public Attributes
bool	prompts = false
	Whether the server advertises prompts.
bool	resources = false
	Whether the server advertises resources.
bool	tools = false
	Whether the server advertises tools.
bool	logging = false
	Whether the server advertises logging.
bool	completions = false
	Whether the server advertises completions.

Enumeration Type Documentation

MCPProtocolVersion

enum class sourcemeta::core::MCPProtocolVersion : std::uint8_t

strong

The supported MCP protocol revisions.

Enumerator
V_2025_03_26	The MCP 2025-03-26 protocol revision.
V_2025_06_18	The MCP 2025-06-18 protocol revision.
V_2025_11_25	The MCP 2025-11-25 protocol revision.

Function Documentation

mcp_is_request_method()

auto sourcemeta::core::mcp_is_request_method ( const JSON::StringView method ) -> bool

constexprnoexcept

Check whether the given method name corresponds to an MCP request method (notifications excluded). For example:

#include <sourcemeta/core/mcp.h>
#include <cassert>
 
assert(sourcemeta::core::mcp_is_request_method("initialize"));
assert(!sourcemeta::core::mcp_is_request_method("notifications/initialized"));

mcp_make_error_resource_not_found()

SOURCEMETA_CORE_MCP_EXPORT auto sourcemeta::core::mcp_make_error_resource_not_found

(

const sourcemeta::core::JSON &

identifier

)

-> sourcemeta::core::JSON

Build a JSON-RPC error envelope reporting that an MCP resource URI could not be resolved. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/mcp.h>
#include <cassert>
 
const auto identifier{sourcemeta::core::JSON{3}};
const auto envelope{
    sourcemeta::core::mcp_make_error_resource_not_found(identifier)};
assert(envelope.at("error").at("code").to_integer() == -32002);

mcp_make_initialize_result()

SOURCEMETA_CORE_MCP_EXPORT auto sourcemeta::core::mcp_make_initialize_result	(	const sourcemeta::core::JSON &	request,
		const MCPServerCapabilities &	capabilities,
		const MCPImplementation &	server,
		const JSON::StringView	instructions = {} ) -> sourcemeta::core::JSON

Build the JSON-RPC envelope returned in response to an MCP initialize request. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/mcp.h>
#include <cassert>
 
const auto request{sourcemeta::core::parse_json(R"JSON({
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": { "protocolVersion": "2025-11-25" }
})JSON")};
const sourcemeta::core::MCPServerCapabilities capabilities;
const sourcemeta::core::MCPImplementation server{"srv", "1.0.0"};
const auto envelope{sourcemeta::core::mcp_make_initialize_result(
    request, capabilities, server)};
assert(envelope.at("result").at("protocolVersion").to_string() ==
       "2025-11-25");

mcp_make_resource()

SOURCEMETA_CORE_MCP_EXPORT auto sourcemeta::core::mcp_make_resource	(	const JSON::StringView	uri,
		const JSON::StringView	name,
		const JSON::StringView	mime_type,
		const JSON::StringView	description = {},
		const std::optional< std::size_t >	size = std::nullopt,
		const std::optional< double >	priority = std::nullopt ) -> sourcemeta::core::JSON

Build an MCP resource descriptor as used in resources/list responses. For example:

#include <sourcemeta/core/mcp.h>
#include <cassert>
 
const auto resource{sourcemeta::core::mcp_make_resource(
    "file:///a", "Alpha", "text/plain")};
assert(resource.at("uri").to_string() == "file:///a");

mcp_make_resource_link()

SOURCEMETA_CORE_MCP_EXPORT auto sourcemeta::core::mcp_make_resource_link	(	const MCPProtocolVersion	version,
		const JSON::StringView	uri,
		const JSON::StringView	mime_type,
		const JSON::StringView	name = {},
		const JSON::StringView	description = {} ) -> sourcemeta::core::JSON

Build an MCP content block referencing a resource by URI. For example:

#include <sourcemeta/core/mcp.h>
#include <cassert>
 
const auto block{sourcemeta::core::mcp_make_resource_link(
    sourcemeta::core::MCPProtocolVersion::V_2025_11_25, "file:///foo",
    "text/plain")};
assert(block.at("type").to_string() == "resource_link");

mcp_make_resource_template()

SOURCEMETA_CORE_MCP_EXPORT auto sourcemeta::core::mcp_make_resource_template	(	const JSON::StringView	uri_template,
		const JSON::StringView	name,
		const JSON::StringView	description,
		const JSON::StringView	mime_type ) -> sourcemeta::core::JSON

Build a single entry for an MCP resources/templates/list response. For example:

#include <sourcemeta/core/mcp.h>
#include <cassert>
 
const auto entry{sourcemeta::core::mcp_make_resource_template(
    "file:///{path}", "Files", "Resolves a file path", "text/plain")};
assert(entry.at("uriTemplate").to_string() == "file:///{path}");

mcp_make_resource_text_content()

SOURCEMETA_CORE_MCP_EXPORT auto sourcemeta::core::mcp_make_resource_text_content	(	const JSON::StringView	uri,
		const JSON::StringView	mime_type,
		const JSON::StringView	text ) -> sourcemeta::core::JSON

Build an MCP resources/read content entry of Text flavour. For example:

#include <sourcemeta/core/mcp.h>
#include <cassert>
 
const auto content{sourcemeta::core::mcp_make_resource_text_content(
    "file:///a", "text/plain", "Hello")};
assert(content.at("text").to_string() == "Hello");

mcp_make_resources_read_result()

SOURCEMETA_CORE_MCP_EXPORT auto sourcemeta::core::mcp_make_resources_read_result

(

sourcemeta::core::JSON

contents

)

-> sourcemeta::core::JSON

Wrap a pre-built array of content entries into the MCP resources/read result envelope. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/mcp.h>
#include <cassert>
#include <utility>
 
auto contents{sourcemeta::core::JSON::make_array()};
contents.push_back(sourcemeta::core::mcp_make_resource_text_content(
    "file:///a", "text/plain", "Hello"));
const auto result{
    sourcemeta::core::mcp_make_resources_read_result(std::move(contents))};
assert(result.at("contents").size() == 1);

mcp_make_text_block()

SOURCEMETA_CORE_MCP_EXPORT auto sourcemeta::core::mcp_make_text_block

(

const JSON::StringView

text

)

-> sourcemeta::core::JSON

Build an MCP Text content block carrying the given text payload. For example:

#include <sourcemeta/core/mcp.h>
#include <cassert>
 
const auto block{sourcemeta::core::mcp_make_text_block("hello")};
assert(block.at("type").to_string() == "text");
assert(block.at("text").to_string() == "hello");

mcp_make_tool_descriptor()

SOURCEMETA_CORE_MCP_EXPORT auto sourcemeta::core::mcp_make_tool_descriptor	(	const MCPProtocolVersion	version,
		const JSON::StringView	name,
		const JSON::StringView	description,
		sourcemeta::core::JSON	input_schema,
		std::optional< sourcemeta::core::JSON >	output_schema = std::nullopt,
		const MCPToolAnnotations &	annotations = {} ) -> sourcemeta::core::JSON

Build a single entry for an MCP tools/list response. For example:

#include <sourcemeta/core/mcp.h>
#include <cassert>
 
const auto entry{sourcemeta::core::mcp_make_tool_descriptor(
    sourcemeta::core::MCPProtocolVersion::V_2025_11_25, "say", "Says hello",
    sourcemeta::core::parse_json(R"({ "type": "object" })"))};
assert(entry.at("name").to_string() == "say");

mcp_make_tool_error()

SOURCEMETA_CORE_MCP_EXPORT auto sourcemeta::core::mcp_make_tool_error	(	const sourcemeta::core::JSON &	identifier,
		const JSON::StringView	message ) -> sourcemeta::core::JSON

Build a JSON-RPC envelope wrapping a failed MCP tool call response with the given error message. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/mcp.h>
#include <cassert>
 
const auto identifier{sourcemeta::core::JSON{1}};
const auto envelope{
    sourcemeta::core::mcp_make_tool_error(identifier, "Boom")};
assert(envelope.at("result").at("isError").to_boolean() == true);

mcp_make_tool_success() [1/2]

SOURCEMETA_CORE_MCP_EXPORT auto sourcemeta::core::mcp_make_tool_success	(	const MCPProtocolVersion	version,
		const sourcemeta::core::JSON &	identifier,
		sourcemeta::core::JSON	result ) -> sourcemeta::core::JSON

Build a JSON-RPC envelope wrapping a successful MCP tool call response from the given result payload. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/mcp.h>
#include <cassert>
#include <utility>
 
const auto identifier{sourcemeta::core::JSON{1}};
auto result{sourcemeta::core::JSON::make_object()};
result.assign("foo", sourcemeta::core::JSON{42});
const auto envelope{sourcemeta::core::mcp_make_tool_success(
    sourcemeta::core::MCPProtocolVersion::V_2025_11_25, identifier,
    std::move(result))};
assert(envelope.at("result").at("isError").to_boolean() == false);

mcp_make_tool_success() [2/2]

SOURCEMETA_CORE_MCP_EXPORT auto sourcemeta::core::mcp_make_tool_success	(	const MCPProtocolVersion	version,
		const sourcemeta::core::JSON &	identifier,
		sourcemeta::core::JSON	structured,
		sourcemeta::core::JSON	content_blocks ) -> sourcemeta::core::JSON

Build a JSON-RPC envelope wrapping a successful MCP tool call response from caller-provided content blocks and a structured payload. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/mcp.h>
#include <cassert>
#include <utility>
 
const auto identifier{sourcemeta::core::JSON{1}};
auto structured{sourcemeta::core::JSON::make_object()};
structured.assign("ok", sourcemeta::core::JSON{true});
auto blocks{sourcemeta::core::JSON::make_array()};
blocks.push_back(sourcemeta::core::mcp_make_text_block("done"));
const auto envelope{sourcemeta::core::mcp_make_tool_success(
    sourcemeta::core::MCPProtocolVersion::V_2025_11_25, identifier,
    std::move(structured), std::move(blocks))};
assert(envelope.at("result").at("isError").to_boolean() == false);

mcp_protocol_version_string()

auto sourcemeta::core::mcp_protocol_version_string ( const MCPProtocolVersion version ) -> JSON::StringView

constexprnoexcept

Get the canonical wire-format string for an MCP protocol version. For example:

#include <sourcemeta/core/mcp.h>
#include <cassert>
 
assert(sourcemeta::core::mcp_protocol_version_string(
           sourcemeta::core::MCPProtocolVersion::V_2025_11_25) ==
       "2025-11-25");

mcp_resolve_protocol_version()

auto sourcemeta::core::mcp_resolve_protocol_version ( const JSON::StringView header ) -> std::optional< MCPProtocolVersion >

constexprnoexcept

Resolve an MCP-Protocol-Version header value into a known protocol version, or std::nullopt when the value is unrecognised. An absent header resolves to the oldest supported version per the Streamable HTTP transport. For example:

#include <sourcemeta/core/mcp.h>
#include <cassert>
 
const auto resolved{
    sourcemeta::core::mcp_resolve_protocol_version("2025-11-25")};
assert(resolved.has_value());
assert(resolved.value() ==
       sourcemeta::core::MCPProtocolVersion::V_2025_11_25);

mcp_supports_implementation_description()

auto sourcemeta::core::mcp_supports_implementation_description ( const MCPProtocolVersion version ) -> bool

constexprnoexcept

Whether the given protocol version supports the description field on the implementation info object.

mcp_supports_implementation_title()

auto sourcemeta::core::mcp_supports_implementation_title ( const MCPProtocolVersion version ) -> bool

constexprnoexcept

Whether the given protocol version supports the title field on the implementation info object.

mcp_supports_implementation_website_url()

auto sourcemeta::core::mcp_supports_implementation_website_url ( const MCPProtocolVersion version ) -> bool

constexprnoexcept

Whether the given protocol version supports the websiteUrl field on the implementation info object.

mcp_supports_jsonrpc_batching()

auto sourcemeta::core::mcp_supports_jsonrpc_batching ( const MCPProtocolVersion version ) -> bool

constexprnoexcept

Whether the given protocol version supports JSON-RPC 2.0 batching.

mcp_supports_output_schema()

auto sourcemeta::core::mcp_supports_output_schema ( const MCPProtocolVersion version ) -> bool

constexprnoexcept

Whether the given protocol version supports per-tool outputSchema.

mcp_supports_resource_link_content()

auto sourcemeta::core::mcp_supports_resource_link_content ( const MCPProtocolVersion version ) -> bool

constexprnoexcept

Whether the given protocol version supports resource_link content blocks.

mcp_supports_structured_content()

auto sourcemeta::core::mcp_supports_structured_content ( const MCPProtocolVersion version ) -> bool

constexprnoexcept

Whether the given protocol version supports structuredContent in tool results.

mcp_tool_call_arguments()

SOURCEMETA_CORE_MCP_EXPORT auto sourcemeta::core::mcp_tool_call_arguments

(

const sourcemeta::core::JSON &

envelope

)

-> const sourcemeta::core::JSON *

Borrow the arguments object from a JSON-RPC tools/call envelope, or return nullptr if no arguments object is present. The returned pointer is valid for the lifetime of the input envelope. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/mcp.h>
#include <cassert>
 
const auto envelope{sourcemeta::core::parse_json(R"JSON({
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "foo", "arguments": { "x": 1 } }
})JSON")};
const auto *arguments{sourcemeta::core::mcp_tool_call_arguments(envelope)};
assert(arguments != nullptr);
assert(arguments->at("x").to_integer() == 1);

Variable Documentation

MCP_CODE_RESOURCE_NOT_FOUND

std::int64_t sourcemeta::core::MCP_CODE_RESOURCE_NOT_FOUND {-32002}

constexpr

The MCP error code returned when a requested resource cannot be found.

MCP_CODE_URL_ELICITATION_REQUIRED

std::int64_t sourcemeta::core::MCP_CODE_URL_ELICITATION_REQUIRED {-32042}

constexpr

The MCP error code indicating that the client must complete a URL elicitation flow before retrying.

MCP_METHOD_INITIALIZE

JSON::StringView sourcemeta::core::MCP_METHOD_INITIALIZE {"initialize"}

constexpr

The MCP method name for the initialize request.

MCP_METHOD_NOTIFICATIONS_INITIALIZED

JSON::StringView sourcemeta::core::MCP_METHOD_NOTIFICATIONS_INITIALIZED

constexpr

Initial value:

{
    "notifications/initialized"}

The MCP method name for the notifications/initialized notification.

MCP_METHOD_PING

JSON::StringView sourcemeta::core::MCP_METHOD_PING {"ping"}

constexpr

The MCP method name for the ping request.

MCP_METHOD_RESOURCES_LIST

JSON::StringView sourcemeta::core::MCP_METHOD_RESOURCES_LIST {"resources/list"}

constexpr

The MCP method name for the resources/list request.

MCP_METHOD_RESOURCES_READ

JSON::StringView sourcemeta::core::MCP_METHOD_RESOURCES_READ {"resources/read"}

constexpr

The MCP method name for the resources/read request.

MCP_METHOD_RESOURCES_TEMPLATES_LIST

JSON::StringView sourcemeta::core::MCP_METHOD_RESOURCES_TEMPLATES_LIST

constexpr

Initial value:

{
    "resources/templates/list"}

The MCP method name for the resources/templates/list request.

MCP_METHOD_TOOLS_CALL

JSON::StringView sourcemeta::core::MCP_METHOD_TOOLS_CALL {"tools/call"}

constexpr

The MCP method name for the tools/call request.

MCP_METHOD_TOOLS_LIST

JSON::StringView sourcemeta::core::MCP_METHOD_TOOLS_LIST {"tools/list"}

constexpr

The MCP method name for the tools/list request.