gizai:mcp

the Model Context Protocol (Streamable HTTP, revision 2025-06-18) for agents. A plugin is an MCP server a person adds to a chat: tools reads its tool list as agent tools (gizai:agent), each call a tool call in a session of its own, and a tool the server marks read-only (readOnlyHint) runs without the person's approval. handle is the other end: one JSON-RPC message to an MCP server whose tools are agent tools.

import * as Mcp from "gizai:mcp";

Types

Header

type Header = { name: string; value: string; }

An HTTP header a plugin sends with each request, as a key (Authorization: Bearer ...).

• name: string
• value: string

Plugin

type Plugin = { id: string; name: string; address: string; headers: Vec<Header>; enabled: bool; }

An MCP server added to a chat, as a page keeps it in a row: its id, the name its tools take as their prefix, its Streamable HTTP address, the headers it needs (secrets the model never sees) and whether its tools are offered.

• id: string
• name: string
• address: string
• headers: Vec<M29.Header>
• enabled: bool

Offered

type Offered = { tools: Vec<Agent.Tool>; problems: Vec<string>; }

The tools of the enabled plugins of plugins, and why each plugin that could not be read was left out.

• tools: Vec<M19.Tool>
• problems: Vec<string>

Server

type Server = { name: string; version: string; instructions: string; }

Who an MCP server is: its name and version, and the instructions a client gives its model.

• name: string
• version: string
• instructions: string

Functions

toolName

function toolName(name: string, tool: string): string

A name a model API accepts for tool TOOL of plugin NAME: NAME_TOOL in [a-zA-Z0-9_], at most 64 characters.

Effects: fail.

tools

function tools(sys: System, p: Plugin, inside: bool = false): Vec<Agent.Tool> throws string

The tools of plugin p as agent tools named NAME_TOOL (toolName), read once now; each call runs on the server in a session of its own. A tool the server marks read-only (readOnlyHint) is read-only. inside lets the address be on this computer or its network; otherwise only the public Internet is reached.

Effects: fail, read, write, console, io.

offered

function offered(sys: System, plugins: Vec<Plugin>, inside: bool = false): Offered

What the enabled plugins of PLUGINS offer (Offered); inside lets their addresses be on this computer or its network (tools).

Effects: fail, read, write, console, io.

toolList

function toolList(tools: Vec<Agent.Tool>): JsonValue

The tool list MCP answers for tools: each one's name, description, input schema and its read-only hint.

Effects: fail.

rpcReply

function rpcReply(id: JsonValue, result: JsonValue): Http.Response

A JSON-RPC result over HTTP: 200 with the message (MCP's and A2A's servers).

Effects: fail.

rpcFailure

function rpcFailure(id: JsonValue, code: i64, message: string): Http.Response

A JSON-RPC error over HTTP: 200 with the message, as the transport did its part.

Effects: fail.

rpcMessage

function rpcMessage(request: Http.Request): Result<JsonValue, Http.Response>

The JSON-RPC message of a POST's body, or the answer that refuses it.

Effects: fail.

unauthorized

function unauthorized(realm: string, message: string): Http.Response

A call without a token: 401 with the Bearer challenge of REALM, and MESSAGE as the error.

Effects: fail.

handle

function handle(request: Http.Request, server: Server, tools: Vec<Agent.Tool>): Http.Response

One JSON-RPC message to the stateless MCP server server whose tools are tools, answered with JSON: initialize, ping, and the tool list and tool calls (the tool's error is a result the client reads as isError). A notification gets 202 and no answer; batches are not accepted.

Effects: fail, read, write, console, io.

Constants

PROTOCOL

const PROTOCOL = "2025-06-18"

The MCP revision both ends speak.

MOST_TOOLS

const MOST_TOOLS = 64

The most tools one plugin offers, and the most pages of a tool list read.