#mcp API reference

Model Context Protocol (https://modelcontextprotocol.io) - the stateless JSON-RPC 2.0 surface an LLM host and an MCP peer speak. This module is both a server (expose tools / resources / prompts to a host) and a client (call a remote MCP server) over either HTTP or a launched stdio subprocess. It is JSON-RPC 2.0 on the wire, so the HTTP client is a thin layer over jsonrpc (which is over http + json) and the server is a purpose-built router (handle) that dispatches only to registered items - unlike jsonrpc.handle's open name dispatch, MCP is an allow-list.

A Server is built value-semantically: server(name, version) then addTool / addResource / addPrompt, each returning a fresh Server. Each registered item is handled by a top-level func NAME(arg as json.Value) in the entry program, passed as a func value and called through its home interpreter (the same mechanism the web module uses), so it resolves its own imports and builds its json.Value result in the entry program's context. handle(server, requestBody) -> replyBody is the transport- agnostic dispatcher; serveStdio(server) runs the primary stdio transport (newline-delimited JSON-RPC on the program's own stdin/stdout).

Scope: the stateless protocol only. No SSE, no sessions. The stdio server (serveStdio), the HTTP client (connect, over jsonrpc), and the stdio subprocess client (connectStdio, over os.run) are all implemented; the stdio client's exchange is one-shot (launch, handshake + op, read replies) since there is no persistent child pipe. Because it uses jsonrpc / http / os.run, this module needs the default jennifer binary.

Security. A tool call is dispatched only when the tool name is in the registry; an unknown tool is a tool error, not an arbitrary-name dispatch. A handler that throws yields a generic error to the peer - the thrown message is never put on the wire, matching jsonrpc's posture.

Import with import "mcp.j" as mcp;. See the mcp guide for prose and examples.

#Functions

#mcp.addPrompt(server as Server, name as string, description as string, arguments as list of PromptArg, handler as func)

Register a prompt, returning a fresh server (value-semantic). arguments declares the arguments a host should collect (build each with promptArg; pass [] for a prompt that takes none).

Parameters

• server {Server} - the server to extend
• name {string} - the prompt's unique name
• description {string} - a description of the prompt
• arguments {list of PromptArg} - the declared arguments (may be empty)
• handler {func} - the handler func value that builds the messages

Returns {Server} - a server with the prompt added

#mcp.addResource(server as Server, uri as string, name as string, description as string, mimeType as string, handler as func)

Register a resource, returning a fresh server (value-semantic).

Parameters

• server {Server} - the server to extend
• uri {string} - the resource's unique URI
• name {string} - a short display name
• description {string} - a description of the resource
• mimeType {string} - the content type of the resource's text
• handler {func} - the handler func value that produces the content

Returns {Server} - a server with the resource added

#mcp.addTool(server as Server, name as string, description as string, inputSchema as json.Value, handler as func)

Register a tool, returning a fresh server (value-semantic).

Parameters

• server {Server} - the server to extend
• name {string} - the tool's unique name
• description {string} - a description of the tool
• inputSchema {json.Value} - the JSON Schema for the tool's arguments
• handler {func} - the handler func value the call dispatches to

Returns {Server} - a server with the tool added

#mcp.callTool(client as Client, name as string, arguments as json.Value)

Call a remote tool by name. Returns the whole tool result (a content array plus an isError flag), so the caller can check isError.

Parameters

• client {Client} - the MCP client
• name {string} - the tool name
• arguments {json.Value} - the tool arguments object

Returns {json.Value} - the tools/call result

#mcp.connect(endpoint as string)

Connect to a remote MCP server over HTTP.

Parameters

• endpoint {string} - the MCP endpoint URL (http:// or https://)

Returns {Client} - a configured client

#mcp.connectStdio(argv as list of string)

Connect to an MCP server launched as a subprocess over stdio - the primary MCP transport (a host runs the server and speaks newline-delimited JSON-RPC on its stdin/stdout). argv is the server command line (program first). Because the exchange is one-shot (os.run, no persistent pipe), each call launches the server, sends the initialize handshake plus the operation as newline-delimited JSON on stdin, closes stdin, and reads the replies from stdout - so a stateless server sees a complete short session per call. Needs the default binary (os.run).

Parameters

• argv {list of string} - the server command line (["python", "srv.py"], ...)

Returns {Client} - a configured stdio client

#mcp.connectWith(endpoint as string, headers as map of string to string)

Connect to a remote MCP server with extra request headers (auth, ...).

Parameters

• endpoint {string} - the MCP endpoint URL
• headers {map of string to string} - headers sent with every request

Returns {Client} - a configured client

#mcp.getPrompt(client as Client, name as string, arguments as json.Value)

Get a remote prompt by name. Returns the whole prompts/get result (a description plus the messages array).

Parameters

• client {Client} - the MCP client
• name {string} - the prompt name
• arguments {json.Value} - the prompt arguments object

Returns {json.Value} - the prompts/get result

#mcp.handle(server as Server, requestBody as string)

Dispatch a single JSON-RPC request body against the server and return the reply body (transport-agnostic: wire it to httpd / net / stdio). A notification (no id, or any notifications/ method) yields "". A parse failure is a -32700 reply; an unknown protocol method is -32601. A tools/call to an unknown tool, or a tool handler that throws, is a successful reply carrying a tool result with isError: true (the thrown message is never put on the wire).

Parameters

• server {Server} - the server whose registries route the request
• requestBody {string} - the raw request JSON

Returns {string} - the reply JSON, or "" when no reply is owed

#mcp.initialize(client as Client)

Perform the initialize handshake and return the server's result (its protocol version, capabilities, and serverInfo). Per the MCP lifecycle, this also sends the required notifications/initialized once the handshake succeeds, so the session is ready for further requests. Throws Error{kind: "jsonrpc"} on any transport or protocol failure.

Parameters

• client {Client} - the MCP client

Returns {json.Value} - the server's initialize result

#mcp.listPrompts(client as Client)

List the remote server's prompts. Returns the prompts array from the prompts/list result.

Parameters

• client {Client} - the MCP client

Returns {json.Value} - the array of prompt descriptors

#mcp.listResources(client as Client)

List the remote server's resources. Returns the resources array from the resources/list result.

Parameters

• client {Client} - the MCP client

Returns {json.Value} - the array of resource descriptors

#mcp.listTools(client as Client)

List the remote server's tools. Returns the tools array from the tools/list result.

Parameters

• client {Client} - the MCP client

Returns {json.Value} - the array of tool descriptors

#mcp.promptArg(name as string, description as string, required as bool)

Build one prompt argument declaration for addPrompt.

Parameters

• name {string} - the argument's name
• description {string} - a description of the argument
• required {bool} - whether the host must supply it

Returns {PromptArg} - the argument declaration

#mcp.property(schema as json.Value, name as string, jsonType as string, description as string, required as bool)

Add a property to a schema, returning a fresh schema. Sets properties/<name> = {type, description} and appends name to required when required is true.

Parameters

• schema {json.Value} - the schema to extend
• name {string} - the property name
• jsonType {string} - the JSON Schema type ("string", "integer", ...)
• description {string} - a description of the property
• required {bool} - whether the property is required

Returns {json.Value} - the extended schema

#mcp.readResource(client as Client, uri as string)

Read a remote resource by URI. Returns the whole resources/read result (a contents array).

Parameters

• client {Client} - the MCP client
• uri {string} - the resource URI

Returns {json.Value} - the resources/read result

#mcp.schema()

Build an empty JSON Schema object skeleton (type: object) for a tool's inputSchema. Add fields with property.

Returns {json.Value} - a {"type":"object","properties":{},"required":[]} skeleton

#mcp.serveStdio(server as Server)

Run the stdio MCP server: read newline-delimited JSON-RPC requests from the program's own stdin, dispatch each through handle, and write each non-empty reply to stdout. Blank lines are skipped; the loop ends at EOF. This is the primary MCP transport (an LLM host launches the program and speaks to it over stdin/stdout).

Parameters

• server {Server} - the server whose registries route each request

#mcp.server(name as string, version as string)

Build an empty server with the given identity.

Parameters

• name {string} - the server name
• version {string} - the server version

Returns {Server} - a server with no registered items

#Structs

#mcp.Client

An MCP client. Over HTTP (connect / connectWith) it wraps a jsonrpc.Client; over stdio (connectStdio) it holds the server's argv and drives it as a subprocess. The same call surface (initialize / listTools / callTool / ...) works for both transports.

#mcp.Prompt

A prompt template the server exposes. Its handler is a func value func NAME(arguments as json.Value) returning the prompt messages as a json.Value; arguments declares what a host should collect (surfaced by prompts/list).

#mcp.PromptArg

One argument a prompt declares, so a host can collect it before prompts/get. Build with promptArg.

#mcp.Resource

A resource the server exposes. Its handler is a func value func NAME(uri as json.Value) returning the resource's text.

#mcp.Server

An MCP server: an identity plus registries of tools, resources, and prompts. Value-semantic; build with server and the add* functions.

#mcp.Tool

A tool the server exposes. Its handler is a func value func NAME(args as json.Value) in the entry program that runs when the tool is called.