MGC Blackbox — Multi‑Agent Secure Execution Engine

1. Overview — What MGC Blackbox Is

MGC Blackbox is a local encrypted execution layer.

It lets AI agents, system scripts, and human users store, execute, and delegate sensitive information or scripts without ever exposing plaintext.

The core promise:

• Store sensitive data (tokens, passwords, configs).
• Store scripts (logic, workflows, automation).
• Execute stored scripts with structured argparse parameters.
• Seal scripts for delegated execution — the original owner keeps control.
• List stored entries (metadata only, never plaintext).
• Open WebUI for human operations.

All data is encrypted locally with AES-256. AI can execute but can never read the plaintext.

---

2. Typical Scenarios — Why You'd Use MGC

Read this section first. These three scenarios are the reason MGC exists. The rest of the document is the technical reference.

---

Scenario A — Zero-Exposure API Keys

Store an API key in MGC once. Reference it from your script by name at runtime. The plaintext key never appears in your script source, your working directory, or your command line.

The script (this is what you actually write)

import os
import requests
import openai

# Read MGC access token (one-time; store outside any shared location)
with open(os.path.expanduser("~/.mgc/database/mgc_black_box/.mgc_token")) as f:
    MGC_TOKEN = f.read().strip()

# Look up the API key from MGC at runtime — never write it in plaintext
resp = requests.post(
    "http://127.0.0.1:57219/api/mgc/sensitive/get",
    headers={"X-MGC-Token": MGC_TOKEN},
    json={"info_type": "token", "info_owner": "openai_api_key"},
)
resp.raise_for_status()
key = resp.json()["data"]

client = openai.OpenAI(api_key=key)
client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "hello"}],
)

What you get:

• The script source contains zero references to the actual API key.
• You can email the script, commit it to git, share it on Slack — the key is safe.
• The key only exists in plaintext inside the MGC process boundary, which is encrypted at rest.
• The MGC_TOKEN itself grants retrieval access, not the secret value — keep it on the same host as MGC.

MGC exposes a REST API (see §9), not a Python client module. To retrieve an entry from a Python script, call the HTTP endpoint directly using requests (or httpx).

---

Scenario B — AI Agents Calling Your Scripts Without Seeing Them

Store your script with info_type='script'. MGC parses the script's argparse arguments and stores them as a structured ext02 field. The AI agent then calls mgc_run with just an owner name and runtime args — it never sees the script source, the embedded credentials, or the storage internals.

Step 1: You store the script (one-time)

mgc_save(
    info_type="script",
    info_owner="weather_report",
    ext01="python",
    content='
import argparse, requests
parser = argparse.ArgumentParser()
parser.add_argument("--city", default="Beijing")
parser.add_argument("--api_key", default=__import__("os").environ["OPENAI_KEY"])
args = parser.parse_args()
print(requests.get(f"https://wttr.in/{args.city}?format=j1", headers={"X-API-Key": args.api_key}).text)
'
)
# MGC auto-fills ext02 with ["--city", "Beijing"]

Step 2: The AI agent calls it (anytime, zero visibility)

AI: "Give me the weather for Shanghai."
Agent: mgc_find(info_owner="weather")          # discover entry + see default ext02
        mgc_run(info_owner="weather_report",
                ext02='["--city", "Shanghai"]') # override args at runtime
        → { "pid": 12345, "status": "started" }

What the AI sees:

• The script name (weather_report).
• The runtime args it passed (--city Shanghai).
• The status (started).

What the AI does NOT see:

• The script source.
• The API key retrieval logic (os.environ["OPENAI_KEY"]).
• How MGC encrypts or stores the data.

You maintain the script. AI drives it. Neither side exposes the other.

---

Scenario C — Distribute a Sealed Script Across MGC Nodes

This is the killer feature for team workflows. Encrypt your script + dependencies so a target MGC node can execute but cannot modify, redistribute, or read the plaintext.

The flow

You (Node A)                        Target Node B
─────────────                       ─────────────
1. mgc_get(NODE_PUB)                (already has RSA keypair)
   → returns Node B's public key

2. mgc_seal(                        (nothing to do on B yet)
     info_owner="my_report",
     ext04=,
     info_type="script",
   )
   → returns sealed capsule:
     - AES-encrypted script body
     - AES key wrapped with Node B's RSA public key

3. Hand over capsule
   (email / USB / any channel)

                                     4. mgc_save(
                                          info_type="script",
                                          info_owner="my_report",
                                          content=,
                                          ext01="python",
                                          ext03=,
                                        )
                                     → encrypted bytes stored as-is

                                     5. mgc_run(info_owner="my_report")
                                        → Node B decrypts and runs.
                                          Node B can execute but:
                                          • cannot read plaintext script
                                          • cannot modify the body
                                          • cannot re-seal for Node C
                                          (because the AES key is bound to B's RSA key)

Cross-platform note

Cross-platform sealed scripts: be aware of semantic differences between operating systems (path separators, shell behavior, available tools). Use pathlib.Path or / for paths, and avoid platform-specific APIs in the script body.

Why this matters

• Execute-only licenses: distribute a script to a contractor, vendor, or partner without giving them source or transferable rights.
• No DRM server: the cryptographic binding is intrinsic to the capsule. Works offline.
• Ownership retained: you can re-seal with a new target key. Old copies become unusable.

---

3. Installation & Runtime — How to Install and Run MGC

3.1 Requirements

• An MCP-compatible agent runtime (Claude Desktop, Cursor, Trae, etc.) for AI integration.
• A modern browser for WebUI access.

Supported Python × OS matrix

3.2 Install MGC Blackbox

pip install mgc-blackbox

Ensure installation happens in the same Python environment where your MCP agent runs.

3.3 Run MGC in normal mode

Start MGC as a standalone local service:

mgc

Default behavior:

• Starts HTTP server at http://127.0.0.1:57219
• Initializes encrypted database on first run
• Generates access token at ~/.mgc/database/mgc_black_box/.mgc_token

This token is required for all REST API calls.

3.4 Run MGC as an MCP server

If your agent supports MCP, configure:

{
  "mcpServers": {
    "mgc-blackbox": {
      "command": "mgc",
      "args": ["--mcp"],
      "env": { "PYTHONIOENCODING": "utf-8" }
    }
  }
}

In MCP mode, MGC exposes six tools: mgc_save, mgc_get, mgc_run, mgc_list, mgc_seal, mgc_open_webui. AI interacts only through MCP tools. The REST API remains available for system scripts.

Sandbox mode

MGC supports sandboxed environments, but a sandboxed agent cannot use the MGC MCP tools if MGC itself is also running in sandbox mode (some sandbox agents run MCP in the system environment rather than inside the sandbox). To use the MCP tools, install MGC in the system environment, or call the FastAPI directly.

3.5 WebUI access

WebUI is available at:

http://127.0.0.1:57218

Use the WebUI for initialization, manual storage, metadata inspection, database audit, and logs.

---

4. The ext_* Protocol — Field Meanings

Rules

• All ext01–ext30 fields are dynamically passed through MCP / API / WebUI.
• ext02 is a JSON array string when manually set, e.g. '["--start", "2026-08-08"]'. MGC passes it to subprocess.run() verbatim.
• ext04 is required only when sealing (it identifies the recipient).

---

5. MCP Tools — Quick Reference

For full argument schemas and field types, see the MCP server's auto-generated schema (every MCP client surfaces it; AI agents read it directly). This section documents the intent of each tool — when to reach for which.

---

MCP Tools — Quick Reference

For full argument schemas, field types, and return shapes, see the MCP server's auto-generated schema (every MCP client surfaces it; AI agents read it directly). This table documents intent and the most important caveats only.

---

5.1 Recommended Workflows

To look up or run an entry / script, first use mgc_find for a fuzzy search to discover its metadata (e.g. ext01, ext02), then proceed with mgc_get to read content or mgc_run to launch. For exact match, mgc_list is also available.

---

5.2 API: LIKE patterns

The /api/mgc/sensitive/get endpoint accepts SQL LIKE wildcards. For programmatic access:

MCP users should prefer mgc_find (auto-applies wildcards via match_mode) over raw LIKE.

---

6. Invocation Model — Who Uses MGC and How

All three channels share the same encrypted backend; nothing is plaintext on the wire between them and the database.

---

7. Trigger Rules — When AI Should Use Which Tool

---

8. Script Args — How to Use

This section is its own chapter because script execution with argparse parameters is the most common interaction shape between AI and MGC.

8.1 On store (mgc_save)

When you save a Python script with info_type='script', MGC automatically parses the script and assembles its argparse args into a structured ext02 field. You do not need to manually set ext02 for script entries.

The parser supports:

• type=str/int/float/bool, default=
• action='store_true' / 'store_false' / 'append' / 'store_const' / 'count'
• nargs='+' / '*' / '?' / N, choices=
• required, metavar, help, dest

It cannot statically evaluate dynamic defaults such as:

default = today.strftime('%Y-%m-%d')        # ast.Call
default = get_default_output_dir()          # ast.Call
default = my_var                            # ast.Name reference

For these, MGC detects the dynamic expression, extracts only the static args, and surfaces a dynamic_args_detected warning. You can then either re-save the script with literal defaults, or supply your own ext02 manually.

8.2 Recommended workflow at runtime

1. List the entry to see its current ext02:
   • MCP: mgc_list (or call mgc_get / api get with empty params for the full list)
2. Inspect ext02 — it is a JSON list of strings, e.g. ["--start", "2026-08-08 00:00:00", "--verbose"]. Each item is one argv token.
3. Launch with current args (uses the stored ext02 as-is):
   • MCP: mgc_run(info_owner=..., ext01=...) (omit ext02 to use the stored value)
   • API: action='run' without ext02 in the request body
   • WebUI: click the green Run button — it launches directly with the stored args
4. Launch with modified args (when needed):
   • MCP: mgc_run(info_owner=..., ext01=..., ext02='["--start", "2026-12-25 09:00:00"]')
   • API: action='run' with ext02 set in the request body
   • WebUI: click the amber Run with Args button (shown next to Run when ext02 is non-empty) to open the JSON editor modal, edit, then click Run in the modal.

8.3 Format rules for manual ext02

When you choose to enter ext02 manually (rather than letting MGC auto-extract), the value MUST be a valid JSON array string, e.g. '["--start", "2026-08-08 00:00:00"]'.

• The WebUI save form enforces this with a JSON validation check before submission.
• The MCP mgc_save schema documents the same requirement.
• A legacy string (non-JSON) is still accepted by the API for backward compatibility but will trigger split() fallback at runtime.

8.4 Notes

• MGC stores the JSON list as-is and passes it directly to subprocess.run(), so values containing spaces (e.g. "2026-08-08 00:00:00") are preserved correctly.
• The auto-generated ext02 is regenerated on every mgc_save from the script body.
• Manual ext02 overrides are per call only — they do not mutate the stored entry. To persist a new ext02, re-save the script with ext02 in the request body.

---

9. REST API — System / Script Integration

Base URL: http://127.0.0.1:57219

Header: X-MGC-Token:

Token file: ~/.mgc/database/mgc_black_box/.mgc_token

No interactive API docs — MGC explicitly disables /docs and /redoc for security. For full request / response shapes, see the MCP server schema (MCP clients surface it directly to AI agents; for direct API use, see the source code in mgc/presentation/web/router/).

---

10. Security Model — How MGC Protects Data

• All data is encrypted locally (AES-256 at rest).
• AI can execute but never read plaintext.
• Seal is irreversible: once sealed, the original owner can re-seal with a new key but cannot extract the script back.
• Execution rights ≠ ownership: a sealed node can execute but cannot transfer the capsule to a third node.
• Content never leaves the device in plaintext.
• Script execution happens inside the encrypted boundary — subprocess inherits the encrypted state.

---

11. Delete Policy

Delete functionality is available via WebUI only to prevent accidental AI-driven deletion.

---

12. Error Handling

---