mcp

Native Model Context Protocol implementation for V — both client and server, full coverage of the 2025-11-25 revision of the spec.

Capabilities

A comprehensive demo server lives at examples/mcp/server.v.

Quick start — client

import mcp

fn main() {
    mut client := mcp.connect('http://localhost:8000/mcp')!
    init := client.initialize()!
    println(init.server_info.name)
    client.close()
}

Quick start — server

import mcp

fn main() {
    mut server := mcp.new_server(
        name:           'my-v-mcp-server'
        version:        '1.0.0'
        enable_logging: true
    )
    server.add_tool(mcp.Tool{
        name:        'say_hello'
        description: 'Greets the caller'
        annotations: mcp.ToolAnnotations{
            read_only_hint: true
        }
    }, fn (_ mcp.Context, _ string) !mcp.ToolResult {
        return mcp.tool_text_result('Hello, user!')
    })!
    server.serve_stdio()!
}

Cancellation and progress

Tool/resource/prompt handlers receive a Context. When the client supplies a _meta.progressToken, the handler can call ctx.notify_progress(progress, total, message). For long-running work, poll ctx.is_cancelled() regularly — when the client sends notifications/cancelled, the flag flips to true until the request completes.

Server-initiated requests

import mcp
import time

mut server := mcp.new_server(name: 'demo', version: '0')
session_id := 'session'
roots := server.list_roots(session_id, 5 * time.second)!
sampled := server.sample(session_id, mcp.CreateMessageParams{}, 30 * time.second)!
elicited := server.elicit(session_id, mcp.ElicitParams{}, 60 * time.second)!

These block until the client returns the matching JSON-RPC response (or until the timeout fires).

Content blocks

Tool, prompt and resource handlers return arrays of MCP content blocks. The module ships ready-made helpers — pass the result through tool_text_result or compose them by hand:

import mcp

text := mcp.text_content('done')
img := mcp.image_content('AAA=', 'image/png')
audio := mcp.audio_content('BBB=', 'audio/wav')
embedded_text := mcp.embedded_text_resource('res://config', 'application/json', '{}')
embedded_blob := mcp.embedded_blob_resource('res://blob', 'image/png', 'AAA=')
resource_link := mcp.resource_link_content(mcp.Resource{
    uri:  'res://docs'
    name: 'docs'
})

Each helper returns a JSON string conforming to the spec's ContentBlock union (type: "text" | "image" | "audio" | "resource" | "resource_link").

Streamable HTTP details

• POST: returns JSON by default. Returns SSE if the client sends Accept: text/event-stream only.
• GET: opens an SSE stream of queued notifications. Resume with Last-Event-ID.
• DELETE: terminates the session (MCP-Session-Id required).
• 403 on disallowed Origin, 400 on unsupported MCP-Protocol-Version, 406 when Accept lists neither application/json nor text/event-stream.

Tests

v test vlib/mcp

spec_compliance_test.v cross-checks wire shapes against the official schema. Add a case there whenever a payload field changes.

fn audio_content(data string, mime_type string) string

audio_content creates a raw MCP audio content block. data must be the base64-encoded payload and mime_type the IANA media type (e.g. audio/wav).

fn audio_content_with_annotations(data string, mime_type string, annotations Annotations) string

audio_content_with_annotations behaves like audio_content but attaches the provided annotations to the block.

fn connect(url string) !Client

connect creates an MCP client for a streamable HTTP endpoint.

fn connect_http(url string, config ClientConfig) !Client

connect_http creates an MCP client for a streamable HTTP endpoint.

fn connect_stdio(command string, args []string, config ClientConfig) !Client

connect_stdio creates an MCP client that talks to a local stdio server process.

fn decode_notification(raw string) !Notification

decode_notification decodes a JSON payload into an MCP notification.

fn decode_request(raw string) !Request

decode_request decodes a JSON payload into an MCP request.

fn decode_response(raw string) !Response

decode_response decodes a JSON payload into an MCP response.

fn embedded_blob_resource(uri string, mime_type string, blob string) string

embedded_blob_resource creates an embedded MCP binary resource content block. blob must be the base64-encoded payload.

fn embedded_blob_resource_with_annotations(uri string, mime_type string, blob string, annotations Annotations) string

embedded_blob_resource_with_annotations behaves like embedded_blob_resource but attaches the provided annotations to the outer EmbeddedResource.

fn embedded_text_resource(uri string, mime_type string, text string) string

embedded_text_resource creates an embedded MCP text resource content block.

fn embedded_text_resource_with_annotations(uri string, mime_type string, text string, annotations Annotations) string

embedded_text_resource_with_annotations behaves like embedded_text_resource but attaches the provided annotations to the outer EmbeddedResource.

fn image_content(data string, mime_type string) string

image_content creates a raw MCP image content block. data must be the base64-encoded payload and mime_type the IANA media type (e.g. image/png).

fn image_content_with_annotations(data string, mime_type string, annotations Annotations) string

image_content_with_annotations behaves like image_content but attaches the provided annotations to the block.

fn new_client(transport Transport, config ClientConfig) Client

new_client constructs an MCP client on top of a custom transport.

fn new_notification[P](method string, params P) Notification

new_notification constructs an MCP notification with a typed params payload.

fn new_request[I, P](id I, method string, params P) Request

new_request constructs an MCP request with a typed id and params payload.

fn new_response[I, R](id I, result R, err ResponseError) Response

new_response constructs an MCP response with a typed id and result payload.

fn new_server(config ServerConfig) Server

new_server constructs a new MCP server.

fn parse_log_level(value string) ?LogLevel

parse_log_level decodes the wire string for a log level.

fn prompt_text_message(role string, text string) PromptMessage

prompt_text_message creates a prompt message with text content.

fn resource_link_content(resource Resource) string

resource_link_content creates a raw MCP resource_link content block from a Resource description. The block carries the resource's metadata — including any annotations set on the resource — so the host can render or read it later.

fn text_content(text string) string

text_content creates a raw MCP text content item.

fn text_content_with_annotations(text string, annotations Annotations) string

text_content_with_annotations behaves like text_content but attaches the provided annotations (audience, priority, lastModified) to the block.

fn tool_text_result(text string) ToolResult

tool_text_result wraps plain text in an MCP tool result.

fn LogLevel.from[W](input W) !LogLevel

fn SessionTransport.from[W](input W) !SessionTransport

interface Transport {
mut:
	send(message string) !
	receive() !string
	close()
}

Transport is the boundary between MCP messages and the wire format.

type CompletionHandler = fn (ctx Context, current_value string, arguments_json string) !CompletionResult

CompletionHandler returns candidate values for a partial argument value. arguments_json is the JSON object of already-supplied sibling arguments (the spec's context.arguments).

type PromptHandler = fn (ctx Context, arguments string) !GetPromptResult

PromptHandler handles prompts/get for a registered prompt.

type ResourceHandler = fn (ctx Context, uri string) !ReadResourceResult

ResourceHandler handles resources/read for a registered resource URI.

type ToolHandler = fn (ctx Context, arguments string) !ToolResult

ToolHandler handles tools/call for a registered tool.

enum LogLevel {
	debug
	info
	notice
	warning
	error
	critical
	alert
	emergency
}

LogLevel is the RFC 5424 severity used by notifications/message.

fn (l LogLevel) str() string

str returns the wire string for a log level (lowercase per spec).

enum SessionTransport {
	stdio
	http
}

SessionTransport identifies how an MCP session is connected.

struct Annotations {
pub:
	audience      []string @[omitempty]
	priority      ?f64
	last_modified string @[json: lastModified; omitempty]
}

Annotations are the optional rendering hints attached to resources, resource templates and content blocks. audience is a list of MCP Role values (e.g. 'user', 'assistant'); priority is in the [0.0, 1.0] range with higher meaning more important; last_modified is an ISO 8601 timestamp.

struct Client {
mut:
	transport         Transport
	config            ClientConfig
	next_id           int = 1
	initialized       bool
	init_result       InitializeResult
	pending_responses map[string]Response
	notifications     []Notification
	server_requests   []Request
}

fn (mut c Client) initialize() !InitializeResult

initialize starts the MCP initialization handshake using the client's config.

fn (mut c Client) initialize_with[X](capabilities X, client_info Implementation) !InitializeResult

initialize_with starts the MCP initialization handshake using typed capabilities.

fn (mut c Client) send_request(request Request) !Response

send_request sends a typed request and waits for its response.

fn (mut c Client) request_message[P](method string, params P) !Response

request_message sends a method call and returns the raw MCP response.

fn (mut c Client) request[P, R](method string, params P) !R

request sends a method call and decodes its result into Result.

fn (mut c Client) send_notification(notification Notification) !

send_notification sends a typed notification message.

fn (mut c Client) notify[P](method string, params P) !

notify sends a method notification with a typed params payload.

fn (mut c Client) take_notifications() []Notification

take_notifications drains notifications queued while waiting for responses.

fn (mut c Client) take_requests() []Request

take_requests drains server initiated requests queued while waiting for responses.

fn (mut c Client) close()

close releases the underlying transport.

struct ClientConfig {
pub mut:
	protocol_version string         = protocol_version
	client_info      Implementation = Implementation{
		name:    default_client_name
		version: default_client_version
	}
	capabilities     string = '{}'
	headers          map[string]string
}

struct CompletionRef {
pub:
	ref_type string @[json: type] // 'ref/prompt' or 'ref/resource'
	name     string @[omitempty]
	uri      string @[omitempty]
}

CompletionRef identifies the prompt or resource template a completion targets. Prompt refs set name; resource refs set uri.

struct CompletionResult {
pub:
	values   []string
	total    ?int
	has_more ?bool
}

CompletionResult is the payload returned by completion/complete.

struct Context {
pub:
	session_id          string @[json: sessionId]
	request_id          string @[json: requestId]
	method              string
	transport           SessionTransport
	protocol_version    string         @[json: protocolVersion]
	client_info         Implementation @[json: clientInfo]
	client_capabilities string         @[json: clientCapabilities; raw]
	progress_token      string         @[json: progressToken; raw]
mut:
	server &Server = unsafe { nil } @[skip]
}

Context provides request-scoped server metadata to handlers.

fn (ctx Context) is_cancelled() bool

is_cancelled reports whether the client has sent notifications/cancelled for this request. Handlers should poll this for cooperative cancellation.

fn (ctx Context) notify_progress(progress f64, total f64, message string)

notify_progress sends notifications/progress for this request when the client included a _meta.progressToken. total and message are optional (pass 0 / '' to omit).

struct CreateMessageParams {
pub:
	messages          []SamplingMessage
	model_preferences ModelPreferences @[json: modelPreferences]
	system_prompt     string           @[json: systemPrompt; omitempty]
	max_tokens        int              @[json: maxTokens]
	temperature       f64              @[omitempty]
	stop_sequences    []string         @[json: stopSequences; omitempty]
	metadata          string           @[omitempty; raw]
	tools             []Tool           @[omitempty]
	tool_choice       ToolChoice       @[json: toolChoice; omitempty]
	include_context   string           @[json: includeContext; omitempty]
}

CreateMessageParams are the typed parameters for sampling/createMessage.

struct CreateMessageResult {
pub:
	role        string
	content     string @[raw]
	model       string
	stop_reason string @[json: stopReason]
}

CreateMessageResult is the typed payload returned by the client.

struct ElicitParams {
pub:
	mode             string @[omitempty]
	message          string
	requested_schema ElicitSchema @[json: requestedSchema; omitempty]
	url              string       @[omitempty]
	elicitation_id   string       @[json: elicitationId; omitempty]
}

ElicitParams are the typed parameters for elicitation/create. Set mode to 'url' and supply url + elicitation_id to send a URL-mode request; otherwise the call defaults to form mode and requested_schema is expected to describe the form fields.

struct ElicitResult {
pub:
	action  string
	content string @[omitempty; raw]
}

ElicitResult is the typed payload returned by the client.

struct ElicitSchema {
pub:
	type_      string = 'object'   @[json: type]
	properties string   @[raw]
	required   []string @[omitempty]
}

ElicitSchema is the requested object schema sent to the client for elicitation.

struct Empty {}

Empty omits a JSON-RPC field when used with MCP helpers.

fn (e Empty) str() string

str returns the empty string.

struct EmptyObject {}

EmptyObject encodes to an empty JSON object.

fn (e EmptyObject) str() string

str returns the JSON empty object literal.

struct GetPromptResult {
pub:
	description string @[omitempty]
	messages    []PromptMessage
}

GetPromptResult is returned by prompts/get.

struct Icon {
pub:
	src       string
	mime_type string   @[json: mimeType; omitempty]
	sizes     []string @[omitempty]
	theme     string   @[omitempty]
}

Icon describes a UI icon advertised by an MCP implementation, tool, resource, resource template or prompt. src is required; mime_type, sizes and theme are optional metadata mirroring the spec's Icon shape.

struct Implementation {
pub:
	name        string
	version     string
	title       string @[omitempty]
	description string @[omitempty]
	website_url string @[json: websiteUrl; omitempty]
	icons       []Icon @[omitempty]
}

Implementation identifies an MCP client or server implementation. name and version are required; title, description, website_url and icons are optional 2025-11-25 metadata extensions (BaseMetadata + Icons).

struct InitializeParams {
pub:
	protocol_version string         @[json: protocolVersion]
	capabilities     string         @[raw]
	client_info      Implementation @[json: clientInfo]
}

InitializeParams is the typed payload for the initialize request.

struct InitializeResult {
pub:
	protocol_version string         @[json: protocolVersion]
	capabilities     string         @[raw]
	server_info      Implementation @[json: serverInfo]
	instructions     string
}

InitializeResult is the typed result returned by an MCP server after initialization.

struct ListRootsResult {
pub:
	roots []Root
}

ListRootsResult is the typed payload returned by the client to a server roots/list request.

struct ModelHint {
pub:
	name string
}

ModelHint is a name hint for sampling/createMessage model selection.

struct ModelPreferences {
pub:
	hints                 []ModelHint
	cost_priority         f64 @[json: costPriority; omitempty]
	speed_priority        f64 @[json: speedPriority; omitempty]
	intelligence_priority f64 @[json: intelligencePriority; omitempty]
}

ModelPreferences expresses sampling/createMessage routing weights.

struct Notification {
pub:
	jsonrpc string = jsonrpc_version
	method  string
	params  string @[omitempty; raw]
}

Notification is a JSON-RPC notification encoded for MCP.

fn (notification Notification) encode() string

encode serializes the notification to JSON.

fn (notification Notification) decode_params[T]() !T

decode_params decodes the raw notification params into T.

struct Null {}

Null represents the JSON null literal.

fn (n Null) str() string

str returns the JSON null literal.

struct Prompt {
pub:
	name        string
	title       string @[omitempty]
	description string @[omitempty]
	arguments   []PromptArgument
	icons       []Icon @[omitempty]
}

Prompt describes an MCP prompt exposed by the server.

struct PromptArgument {
pub:
	name        string
	description string @[omitempty]
	required    bool
}

PromptArgument describes one prompt argument.

struct PromptMessage {
pub:
	role    string
	content string @[raw]
}

PromptMessage is one message returned by prompts/get.

struct ReadResourceResult {
pub:
	contents []ResourceContents
}

ReadResourceResult is returned by resources/read.

struct Request {
pub:
	jsonrpc string = jsonrpc_version
	id      string @[raw]
	method  string
	params  string @[omitempty; raw]
}

Request is a JSON-RPC request message encoded for MCP.

fn (req Request) encode() string

encode serializes the request to JSON.

fn (req Request) decode_params[T]() !T

decode_params decodes the raw request params into T.

struct Resource {
pub:
	uri         string
	name        string
	title       string @[omitempty]
	description string @[omitempty]
	mime_type   string @[json: mimeType; omitempty]
	size        ?int
	icons       []Icon @[omitempty]
	annotations Annotations
}

Resource describes a concrete MCP resource exposed by the server.

struct ResourceContents {
pub:
	uri       string
	mime_type string @[json: mimeType; omitempty]
	text      string @[omitempty]
	blob      string @[omitempty]
}

ResourceContents contains the result of resources/read.

struct ResourceTemplate {
pub:
	uri_template string @[json: uriTemplate]
	name         string
	title        string @[omitempty]
	description  string @[omitempty]
	mime_type    string @[json: mimeType; omitempty]
	icons        []Icon @[omitempty]
	annotations  Annotations
}

ResourceTemplate describes a parameterized MCP resource URI template.

struct Response {
pub:
	jsonrpc string = jsonrpc_version
	id      string @[raw]
	result  string @[raw]
	error   ResponseError
}

Response is a JSON-RPC response message encoded for MCP.

fn (resp Response) encode() string

encode serializes the response to JSON.

fn (resp Response) decode_result[T]() !T

decode_result decodes the response result into T.

struct ResponseError {
pub:
	code    int
	message string
	data    string @[raw]
}

ResponseError is the JSON-RPC error payload used by MCP responses.

fn (err ResponseError) code() int

code returns the JSON-RPC error code.

fn (err ResponseError) msg() string

msg returns the JSON-RPC error message.

fn (err ResponseError) err() IError

err casts the response error to IError.

struct Root {
pub:
	uri  string
	name string @[omitempty]
}

Root identifies a filesystem-or-URI boundary advertised by the client in response to roots/list.

struct SamplingMessage {
pub:
	role    string
	content string @[raw]
}

SamplingMessage is one message of a sampling/createMessage exchange.

struct Server {
mut:
	server_info           Implementation
	protocol_version      string
	capabilities_override string
	instructions          string
	http_path             string
	allowed_origins       []string
	enable_logging        bool
	http_server           &http.Server = unsafe { nil }
	tools                 map[string]RegisteredTool
	tool_names            []string
	resources             map[string]RegisteredResource
	resource_uris         []string
	resource_templates    map[string]ResourceTemplate
	resource_template_ids []string
	prompts               map[string]RegisteredPrompt
	prompt_names          []string
	completions           map[string]RegisteredCompletion
	state                 shared ServerState
}

Server handles MCP protocol requests for stdio and HTTP transports.

fn (mut s Server) add_tool(tool Tool, handler ToolHandler) !

add_tool registers a tool and its handler.

fn (mut s Server) add_resource(resource Resource, handler ResourceHandler) !

add_resource registers a concrete resource and its read handler.

fn (mut s Server) add_resource_template(template ResourceTemplate) !

add_resource_template registers a resource template exposed by resources/templates/list.

fn (mut s Server) add_prompt(prompt Prompt, handler PromptHandler) !

add_prompt registers a prompt and its handler.

fn (mut s Server) add_completion(ref CompletionRef, argument string, handler CompletionHandler) !

add_completion registers a completion handler for one argument of a prompt or resource template. argument is the argument name being completed.

fn (mut s Server) notify_tools_list_changed()

notify_tools_list_changed broadcasts the tool catalog change notification.

fn (mut s Server) notify_resources_list_changed()

notify_resources_list_changed broadcasts the resource catalog change notification.

fn (mut s Server) notify_prompts_list_changed()

notify_prompts_list_changed broadcasts the prompt catalog change notification.

fn (mut s Server) notify_log(level LogLevel, logger string, data_json string)

notify_log emits a notifications/message payload at level filtered per session by the most recent logging/setLevel call. data_json MUST be a valid JSON value (object preferred per spec). logger is optional.

fn (mut s Server) list_roots(session_id string, timeout time.Duration) !ListRootsResult

list_roots issues roots/list to the session and waits for the response.

fn (mut s Server) sample(session_id string, params CreateMessageParams, timeout time.Duration) !CreateMessageResult

sample issues sampling/createMessage and waits for the LLM result.

fn (mut s Server) elicit(session_id string, params ElicitParams, timeout time.Duration) !ElicitResult

elicit issues elicitation/create and waits for the user-supplied content.

fn (mut s Server) notify_elicitation_complete(session_id string, elicitation_id string)

notify_elicitation_complete emits a notifications/elicitation/complete notification for the session that initiated a URL-mode elicitation. Pass the same elicitation_id that was supplied to elicit() so the client can correlate the out-of-band interaction with its pending request.

fn (mut s Server) notify_resource_updated(uri string)

notify_resource_updated emits notifications/resources/updated to every session that has subscribed to uri.

fn (mut s Server) serve_stdio() !

serve_stdio starts serving MCP messages over stdio using newline framing. MCP 2025-11-25 mandates that stdio messages are delimited by newlines and MUST NOT contain embedded newlines. We bypass libc stdio buffering on the way in (raw read() on fd 0) and flush stdout after every frame on the way out, so peers behind a pipe see responses immediately and the server reacts to each line as soon as it arrives.

fn (mut s Server) serve_http(addr string) !

serve_http starts serving MCP over a single HTTP endpoint.

fn (mut s Server) close()

close stops the HTTP server if it is running.

fn (mut s Server) wait_till_running(params http.WaitTillRunningParams) !int

wait_till_running waits until the HTTP server transitions to the running state.

struct ServerConfig {
pub:
	name             string
	version          string
	title            string
	description      string
	website_url      string
	icons            []Icon
	protocol_version string = protocol_version
	capabilities     string
	instructions     string
	http_path        string = default_http_path
	// enable_logging declares the `logging` capability and lets clients call
	// `logging/setLevel`. Disabled by default — turn on when the server emits
	// `notifications/message` payloads.
	enable_logging bool
	// allowed_origins lists the Origin header values accepted on Streamable
	// HTTP. Use `*` to accept any origin (NOT recommended). When empty the
	// server only accepts requests without an Origin header or from the
	// loopback addresses (`http://localhost[:port]`, `http://127.0.0.1[:port]`,
	// `http://[::1][:port]`, or the literal string `null`).
	allowed_origins []string
}

ServerConfig configures an MCP server instance.

struct Tool {
pub:
	name          string
	title         string @[omitempty]
	description   string @[omitempty]
	input_schema  string = default_tool_input_schema @[json: inputSchema; raw]
	output_schema string @[json: outputSchema; omitempty; raw]
	annotations   ToolAnnotations
	icons         []Icon @[omitempty]
	execution     ToolExecution
}

Tool describes an MCP tool exposed by the server.

struct ToolAnnotations {
pub:
	title            string @[omitempty]
	read_only_hint   ?bool  @[json: readOnlyHint]
	destructive_hint ?bool  @[json: destructiveHint]
	idempotent_hint  ?bool  @[json: idempotentHint]
	open_world_hint  ?bool  @[json: openWorldHint]
}

ToolAnnotations exposes the optional behavioural hints described by the MCP spec (tools/list Annotations object).

struct ToolChoice {
pub:
	mode string
}

ToolChoice configures sampling/createMessage tool-use behaviour. mode is one of 'auto' (default), 'required', or 'none'.

struct ToolExecution {
pub:
	task_support string @[json: taskSupport; omitempty]
}

ToolExecution carries optional execution metadata for a tool. Set task_support to one of 'forbidden', 'optional' or 'required' to advertise tasks/* support; the default (empty) omits the field on the wire.

struct ToolResult {
pub:
	content            string @[omitempty; raw]
	structured_content string @[json: structuredContent; omitempty; raw]
	is_error           bool   @[json: isError]
}

ToolResult is returned by tools/call.