mcp

mcp is a Model Context Protocol module for V.

It provides:

• typed JSON-RPC request, notification, response, and initialize payload helpers
• a synchronous Client that performs the MCP initialize handshake automatically
• a server-side Server with tool, resource, resource template, and prompt registration
• streamable HTTP and stdio transports behind a common transport interface
• queues for server notifications and server-initiated requests
• buffered while waiting for a response

HTTP example

import mcp

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

Stdio example

import mcp

fn main() {
    mut client := mcp.connect_stdio('my-mcp-server', ['--stdio'], mcp.ClientConfig{})!
    client.notify('notifications/cancelled', {
        'requestId': 1
    })!
    client.close()
}

Server example

import mcp

fn main() {
    mut server := mcp.new_server(
        name:    'my-v-mcp-server'
        version: '1.0.0'
    )

    server.add_tool(mcp.Tool{
        name:        'say_hello'
        description: 'Greets a user by name'
    }, fn (_ mcp.Context, _ string) !mcp.ToolResult {
        return mcp.tool_text_result('Hello, user!')
    })!

    server.serve_stdio()!
}

Notes

• Client.request auto-initializes when needed.
• Client.take_notifications and Client.take_requests drain queued server messages.
• The HTTP transport supports JSON responses and text/event-stream POST responses.
• Server.serve_http uses a single MCP endpoint, returns JSON by default, and will return SSE for POST requests that accept only text/event-stream.

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 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 prompt_text_message(role string, text string) PromptMessage

prompt_text_message creates a prompt message with text content.

fn text_content(text string) string

text_content creates a raw MCP text content item.

fn tool_text_result(text string) ToolResult

tool_text_result wraps plain text in an MCP tool result.

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 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 SessionTransport {
	stdio
	http
}

SessionTransport identifies how an MCP session is connected.

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 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]
}

Context provides request-scoped server metadata to handlers.

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 Implementation {
pub:
	name    string
	version string
}

Implementation identifies an MCP client or server implementation.

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 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
}

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]
}

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]
}

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 Server {
mut:
	server_info           Implementation
	protocol_version      string
	capabilities_override string
	instructions          string
	http_path             string
	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
	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) serve_stdio() !

serve_stdio starts serving MCP messages over stdio using Content-Length framing.

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
	protocol_version string = protocol_version
	capabilities     string
	instructions     string
	http_path        string = default_http_path
}

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]
}

Tool describes an MCP tool exposed by the server.

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.