Plugin Author Guide — Shape 1 MCP Subprocess

This is the author-facing companion to docs/plugin-contract.md (the normative contract) and docs/catalog-abi.md (the runtime catalog ABI). The contract tells you *what* the host validates and rejects; this guide walks you through *how to ship* a Shape 1 MCP-subprocess plugin from scratch — manifest, ABI wire format, packaging, install workflow, and a complete worked example.

In v0.1.0 through v0.3.x, Shape 1 (MCP subprocess) is the only externally authorable plugin shape. Shape 2 (gRPC subprocess) is reserved for a v0.4.0 freeze; third-party Shape 2 manifests are rejected at install time with PLUGIN_SHAPE_UNSUPPORTED.

---

1. What a Shape 1 plugin is

A Shape 1 plugin is a subprocess that GUM launches when one of its tools is invoked. The subprocess speaks MCP over stdio (JSON-RPC 2.0 with the standard MCP envelope) — the same wire format any MCP client uses to talk to any MCP server.

Concretely you ship:

1. A manifest (manifest.json) declaring identity, capabilities, sandbox requirements, and the tools the subprocess advertises.
2. An executable that, when launched with no arguments and its stdio connected to the host, behaves as a conforming MCP stdio server. It MUST implement initialize, tools/list, and tools/call.
3. A package (currently any of: GitHub release artifact, Git repo at pinned commit, PyPI wheel/sdist, or a local directory for development).

GUM verifies the executable's SHA-256 at install time, records (executable_path, executable_sha256, argv_normalized, install_root) in the active profile's plugins.lock, and re-hashes on every spawn (spec §8 line 1690). Shell interpreters in executable_path and path escapes outside the install root are rejected with PLUGIN_EXECUTABLE_UNTRUSTED.

---

2. Manifest reference

The manifest is the v1 schema enforced by plugins.LoadManifest. Every field below is required unless marked optional.

{
  "manifest_schema_version": 1,
  "plugin_id": "fli",
  "name": "Flight Search",
  "version": "0.1.0",
  "namespace_owner": "io.example.flights",
  "shape": "mcp-plugin",
  "executable": "bin/fli-mcp",
  "advertised_tools": [
    {
      "name": "search",
      "description": "Search Google Flights for a route on a date range",
      "risk_class": "read"
    }
  ],
  "declared_capabilities": {
    "network": true,
    "fs_write_dir": "",
    "env_allow": ["FLI_USER_AGENT"]
  }
}

Field-by-field

Cross-references

• Namespace ownership rules: docs/plugin-contract.md §third-party namespace ownership.
• Reserved first-party prefixes (gmail, drive, calendar, and similar Google service prefixes): docs/plugin-contract.md §third-party namespace ownership.
• Credential descriptors required when env_allow carries OAuth-bearing vars: docs/plugin-contract.md §credential descriptors.

---

3. Wire ABI

The host launches the executable, connects its stdin/stdout to the JSON-RPC transport, and immediately issues an MCP initialize. The subprocess MUST:

1. Respond to initialize with its capabilities (in particular tools: {listChanged: true} if tools change at runtime — most plugins set this to false).
2. Respond to tools/list with the list of advertised tools and their inputSchemas. Tool names returned here MUST match the advertised_tools[].name in the manifest (unprefixed; the host adds the plug.<plugin_id>. prefix downstream).
3. Respond to tools/call with either a successful MCP CallToolResult or an MCP error envelope.

3.1 The four messages your plugin must handle

(a) initialize request:

// host → plugin
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
  "protocolVersion":"2025-06-18",
  "capabilities":{},
  "clientInfo":{"name":"gum","version":"0.1.0"}
}}

// plugin → host
{"jsonrpc":"2.0","id":1,"result":{
  "protocolVersion":"2025-06-18",
  "capabilities":{"tools":{"listChanged":false}},
  "serverInfo":{"name":"Flight Search","version":"0.1.0"}
}}

(b) tools/list:

// host → plugin
{"jsonrpc":"2.0","id":2,"method":"tools/list"}

// plugin → host
{"jsonrpc":"2.0","id":2,"result":{"tools":[
  {
    "name":"search",
    "description":"Search Google Flights for a route on a date range",
    "inputSchema":{
      "type":"object",
      "additionalProperties":false,
      "properties":{
        "origin":{"type":"string","minLength":3,"maxLength":3},
        "destination":{"type":"string","minLength":3,"maxLength":3},
        "depart_date":{"type":"string","format":"date"},
        "return_date":{"type":"string","format":"date"}
      },
      "required":["origin","destination","depart_date"]
    }
  }
]}}

(c) tools/call:

// host → plugin
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{
  "name":"search",
  "arguments":{"origin":"SFO","destination":"JFK","depart_date":"2026-06-15"}
}}

// plugin → host  (success)
{"jsonrpc":"2.0","id":3,"result":{
  "content":[
    {"type":"text","text":"{\"success\":true,\"data\":{\"itineraries\":[…]}}"}
  ],
  "isError":false
}}

(d) Plugin-local error envelope (spec §8 lines 1624–1641):

When the operation fails, the plugin returns a CallToolResult with isError: true and the body string is a JSON object:

{"success": false,
 "error_code": "RATE_LIMIT|AUTH_EXPIRED|PARSE_FAILURE|SERVICE_DOWN|INVALID_INPUT",
 "error": "human-readable message",
 "retryable": true,
 "retry_after_ms": 5000}

The host maps these to stable GUM codes (plugins.MapPluginError):

Plugins MUST NOT emit stable GUM codes directly (RATE_LIMITED, AUTH_REQUIRED, etc.) — those are the host's vocabulary. Always emit one of the five plugin-local codes above.

---

4. Packaging

4.1 Directory layout

my-plugin/
├── manifest.json            # the v1 manifest above
├── bin/
│   └── fli-mcp              # the executable (executable bit set)
├── README.md                # optional but recommended
└── LICENSE                  # required for non-local installs

For Python (FastMCP-style) plugins, ship a console-script entry point:

my-plugin/
├── manifest.json
├── pyproject.toml           # declares console_scripts = fli-mcp = fli_mcp:main
├── src/
│   └── fli_mcp/
│       ├── __init__.py
│       └── server.py
└── requirements.lock

Remote package installers are not part of the v1 CLI. Package the plugin as a local directory with a manifest and executable, then run gum plugin install on that directory.

4.2 Install commands

Run gum plugin list to confirm the install:

$ gum plugin list
fli    0.1.0   Flight Search

To clear a quarantine after a fix:

$ gum plugin reload fli
reloaded fli

gum plugin remove fli removes the install but preserves the namespace_owner entry in plugins.lock, so a reinstall by the same owner succeeds without re-asserting consent (spec §5.1 transfer procedure).

v0.1.0 note: a dedicated gum plugin validate subcommand is not yet wired. Until it lands (planned for a v0.2.0 ergonomics pass), validate by running gum plugin install ./my-plugin against a scratch profile (--profile=dev + XDG_DATA_HOME=/tmp/...); the install path runs the full v1 manifest validator, namespace check, executable-binding rehash, and (if defined) the canary.

---

5. End-to-end example: a hello plugin in Python

This minimal plugin advertises one tool, hello, which returns a deterministic greeting. It uses the mcp Python SDK's stdio server.

Directory layout:

hello-plugin/
├── manifest.json
├── pyproject.toml
└── src/hello_plugin/__init__.py

manifest.json:

{
  "manifest_schema_version": 1,
  "plugin_id": "hello",
  "name": "Hello",
  "version": "0.1.0",
  "namespace_owner": "io.example.hello",
  "shape": "mcp-plugin",
  "executable": "hello-mcp",
  "advertised_tools": [
    {
      "name": "hello",
      "description": "Return a deterministic greeting for the given name",
      "risk_class": "read"
    }
  ],
  "declared_capabilities": {
    "network": false,
    "fs_write_dir": "",
    "env_allow": []
  }
}

pyproject.toml:

[project]
name = "hello-plugin"
version = "0.1.0"
dependencies = ["mcp>=1.0.0"]

[project.scripts]
hello-mcp = "hello_plugin:main"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

src/hello_plugin/__init__.py:

import json
import sys
from mcp.server.fastmcp import FastMCP

app = FastMCP("Hello")

@app.tool()
def hello(name: str) -> str:
    """Return a deterministic greeting for the given name."""
    # GUM expects either a successful payload or a plugin-local error envelope
    # per spec §8 lines 1624–1641.
    if not name or not isinstance(name, str):
        return json.dumps({
            "success": False,
            "error_code": "INVALID_INPUT",
            "error": "name must be a non-empty string",
            "retryable": False,
        })
    return json.dumps({"success": True, "data": {"greeting": f"Hello, {name}!"}})

def main() -> None:
    app.run()  # stdio transport, blocks until parent closes stdin

Install + smoke-test:

# 1. Build the wheel.
python -m build hello-plugin

# 2. Install into a scratch profile.
GUM_PROFILE=dev gum plugin install ./hello-plugin

# 3. Invoke through the host.
gum plugin run hello hello '{"name":"world"}'
# → {"success":true,"data":{"greeting":"Hello, world!"}}

# 4. Trigger the validator with a bad arg.
gum plugin run hello hello '{"name":""}'
# → host maps INVALID_INPUT → INVALID_ARGS envelope

What was validated end-to-end:

• Manifest schema (manifest_schema_version=1, shape=mcp-plugin, plugin_id regex, namespace_owner).
• Namespace-ownership lock for the hello. prefix in plugins.lock.
• Executable binding (SHA-256 hashed into plugins.lock, re-hashed on every spawn).
• MCP handshake (initialize, tools/list, tools/call).
• Plugin-local error envelope mapped to a stable GUM code (INVALID_INPUT → INVALID_ARGS).

---

6. Common authoring mistakes

---

7. Going further

• Output profiles: ship an output_profile per tool to keep responses compact. See docs/profile-dsl-reference.md for the operator catalogue and worked examples.
• Canaries: declare a [requirements].canary block so cmd/gen-catalog can run a known-good call at build time. Use relative date specifiers (+7d, +2w) to avoid stale fixtures.
• Quarantine + crash recovery: spec §8.6 describes the exponential-backoff window and the gum plugin reload / gum plugin unquarantine recovery commands.
• Plugin-shipped profiles: see docs/plugin-contract.md §profiles for the rules that govern profiles bundled inside a plugin.

For runtime catalog ABI (variant IDs, capability atoms, binding shape), read docs/catalog-abi.md. For the normative install contract and field-level wire requirements, read docs/plugin-contract.md.