# gizai:agent/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. Read-only, destructive and idempotent annotations stay independent of the host's approval policy. `handle` is the other end: one JSON-RPC message to an MCP server whose tools are agent tools.

```gizlang
import * as Mcp from "gizai:agent/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<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<M31.Header>`
- `enabled`: `bool`

### `RemoteTool`

```gizlang
type RemoteTool = { name: string; description: string; parameters: JsonValue; readOnly: bool; destructive: bool; idempotent: bool; }
```

A discovered server tool retains its original call name independently of the model projection.

- `name`: `string`
- `description`: `string`
- `parameters`: `gizlang_json.Json`
- `readOnly`: `bool`
- `destructive`: `bool`
- `idempotent`: `bool`

### `Offered`

```gizlang
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<M18.Tool>`
- `problems`: `Vec<string>`

### `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.

### `discover`

```gizlang
function discover(sys: System, p: Plugin, inside: bool = false): Vec<RemoteTool> throws string
```

Discover protocol tool declarations once, retaining the server's original names.

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

### `tools`

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

Project discovery to the standalone agent API; the protocol has one client owner.

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

### `call`

```gizlang
function call(sys: System, p: Plugin, inside: bool, tool: string, arguments: string): Result<string, string>
```

Calls TOOL of plugin `p` with ARGUMENTS (a JSON object's text) in a session of its own: the text of its content
(its structured content when it has none); a result the server marks isError is the call's error.

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

### `offered`

```gizlang
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`

```gizlang
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`

```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<JsonValue, Http.Response>
```

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

```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.

gizai:agent/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. Read-only, destructive and idempotent annotations stay independent of the host's approval policy. handle is the other end: one JSON-RPC message to an MCP server whose tools are agent tools.

gizlang

import * as Mcp from "gizai:agent/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<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<M31.Header>
enabled: bool

`RemoteTool`

gizlang

type RemoteTool = { name: string; description: string; parameters: JsonValue; readOnly: bool; destructive: bool; idempotent: bool; }

A discovered server tool retains its original call name independently of the model projection.

name: string
description: string
parameters: gizlang_json.Json
readOnly: bool
destructive: bool
idempotent: bool

`Offered`

gizlang

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<M18.Tool>
problems: Vec<string>

`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.

`discover`

gizlang

function discover(sys: System, p: Plugin, inside: bool = false): Vec<RemoteTool> throws string

Discover protocol tool declarations once, retaining the server's original names.

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

`tools`

gizlang

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

Project discovery to the standalone agent API; the protocol has one client owner.

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

`call`

gizlang

function call(sys: System, p: Plugin, inside: bool, tool: string, arguments: string): Result<string, string>

Calls TOOL of plugin p with ARGUMENTS (a JSON object's text) in a session of its own: the text of its content (its structured content when it has none); a result the server marks isError is the call's error.

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

`offered`

gizlang

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`

gizlang

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`

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<JsonValue, Http.Response>

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

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.