# 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. ```gizlang import * as Mcp from "gizai:mcp"; ``` ## Types ### `Header` ```gizlang 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` ```gizlang type Plugin = { id: string; name: string; address: string; headers: Vec
; 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` - `enabled`: `bool` ### `Offered` ```gizlang type Offered = { tools: Vec; problems: Vec; } ``` The tools of the enabled plugins of `plugins`, and why each plugin that could not be read was left out. - `tools`: `Vec` - `problems`: `Vec` ### `Server` ```gizlang 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` ```gizlang 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` ```gizlang function tools(sys: System, p: Plugin, inside: bool = false): Vec 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` ```gizlang function offered(sys: System, plugins: Vec, 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` ```gizlang function toolList(tools: Vec): JsonValue ``` The tool list MCP answers for `tools`: each one's name, description, input schema and its read-only hint. Effects: fail. ### `rpcReply` ```gizlang 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` ```gizlang 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` ```gizlang function rpcMessage(request: Http.Request): Result ``` The JSON-RPC message of a POST's body, or the answer that refuses it. Effects: fail. ### `unauthorized` ```gizlang 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` ```gizlang function handle(request: Http.Request, server: Server, tools: Vec): 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` ```gizlang const PROTOCOL = "2025-06-18" ``` The MCP revision both ends speak. ### `MOST_TOOLS` ```gizlang const MOST_TOOLS = 64 ``` The most tools one plugin offers, and the most pages of a tool list read.