Skip to main content
Glama
macula-io

Macula MCP

by macula-io
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript

mesh_serve

Register a shell command as a callable mesh procedure, letting verified callers invoke it repeatedly until unserved. Useful for exposing local services over the mesh.

Instructions

Serve a procedure on the mesh, answered by a local shell command run once per inbound call (its stdin is the caller's JSON payload, its stdout is the reply, MACULA_MCP_CALLER is the caller's verified node_id). It is served in this agent's own namespace: callers call ~/, which the result names. THIS IS A STANDING INBOUND SURFACE, not a one-shot action: once registered, any mesh caller can trigger the command repeatedly until mesh_unserve is called or this process exits. Never register a command you would not want a stranger able to run repeatedly on this machine. Pair with mesh_unserve to stop serving deliberately. Bytes in the caller's payload appear on stdin as {"$bytes": ""}; write bytes to stdout in the same form. MACULA_MCP_SEALED is 1 when the call came sealed to this agent's KEM key, 0 when it came in the clear; callers seal only when this server runs with MACULA_MCP_KEM_ADVERTISE=1.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
execYesShell command to run once per inbound call. Receives the call's JSON payload on stdin and the caller's node_id in MACULA_MCP_CALLER; its entire stdout is parsed as the JSON reply (empty stdout replies null). Bytes appear as {"$bytes": "<base64>"} both ways.
nameYesThe procedure's name in this agent's own namespace, one segment, e.g. "summarize" (served as ~<node_id>/summarize).
confidentialNo"preferred" (default): with MACULA_MCP_KEM_ADVERTISE=1 this agent's KEM key is named so callers seal, and a clear call is taken only while its last keyless advertisement could still be served, then refused sealed_required, so a caller older than macula 13 / macula-go 0.18 / @macula-io/ts 0.24 cannot call it after that; without it, served in the clear. "required": every clear call is refused (sealed_required); needs MACULA_MCP_KEM_ADVERTISE=1, else code=confidentiality (reason=kem_advertise_disabled), and a caller older than macula 13 / macula-go 0.18 / @macula-io/ts 0.24 cannot call it. "off": served in the clear. To change it on a served name, mesh_unserve it first.
exec_timeout_secondsNoHow long one invocation may run before it's killed (default 10, max 60).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv0.37.0
    • addedInput schema / properties / confidential
      Added value: +{
+  "description": "\"preferred\" (default): with MACULA_MCP_KEM_ADVERTISE=1 this agent's KEM key is named so callers seal, and a clear call is taken only while its last keyless advertisement could still be served, then refused sealed_required, so a caller older than macula 13 / macula-go 0.18 / @macula-io/ts 0.24 cannot call it after that; without it, served in the clear. \"required\": every clear call is refused (sealed_required); needs MACULA_MCP_KEM_ADVERTISE=1, else code=confidentiality (reason=kem_advertise_disabled), and a caller older than macula 13 / macula-go 0.18 / @macula-io/ts 0.24 cannot call it. \"off\": served in the clear. To change it on a served name, mesh_unserve it first.",
+  "enum": [
+    "preferred",
+    "required",
+    "off"
+  ],
+  "type": "string"
+}
    • changedInput schema / properties / exec / description
      Previous value: -"Shell command to run once per inbound call. Receives the call's JSON payload on stdin; its entire stdout is parsed as the JSON reply (empty stdout replies null)."New value: +"Shell command to run once per inbound call. Receives the call's JSON payload on stdin and the caller's node_id in MACULA_MCP_CALLER; its entire stdout is parsed as the JSON reply (empty stdout replies null). Bytes appear as {\"$bytes\": \"<base64>\"} both ways."
    • removedInput schema / properties / host
      Removed value: -{
-  "description": "Station to connect through, \"host[:port]\". Defaults to station-de-frankfurt.macula.io:4433.",
-  "type": "string"
-}
    • addedInput schema / properties / name
      Added value: +{
+  "description": "The procedure's name in this agent's own namespace, one segment, e.g. \"summarize\" (served as ~<node_id>/summarize).",
+  "minLength": 1,
+  "type": "string"
+}
    • removedInput schema / properties / procedure
      Removed value: -{
-  "description": "The procedure name to advertise, e.g. \"my_agent.summarize\".",
-  "minLength": 1,
-  "type": "string"
-}
    • changedInput schema / required
      Previous value: -[
-  "procedure",
-  "exec"
-]New value: +[
+  "name",
+  "exec"
+]
  2. First observedv0.28.7

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does it well: it discloses the standing-surface lifecycle (until mesh_unserve or process exit), the stdin/stdout and byte-encoding contract, and the MACULA_MCP_CALLER/MACULA_MCP_SEALED env semantics. It does not spell out failure/error modes for the command itself, but the security and lifecycle disclosure is strong.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose and the standing-surface warning before the byte/env details. Every sentence earns its place, though the KEM/version detail is dense enough to slightly tax readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a registration/mutation tool with no annotations and no output schema, the description covers lifecycle, security posture, reply channel, and teardown. An agent has everything needed to decide and invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds runtime meaning: it ties the exec contract to the caller's JSON payload and sealed/advertise wiring, and reinforces the name-namespace and confidentiality behavior beyond the raw field descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Serve a procedure on the mesh, answered by a local shell command run once per inbound call') with the exact invocation contract. It is clearly distinguishable from mesh_unserve (which stops serving) and from the read/write siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly frames this as a standing inbound surface rather than a one-shot action, warns against registering commands a stranger could run repeatedly, and names mesh_unserve as the way to stop. The when-to-use and when-to-be-careful conditions are both stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools