vectorstep-gateway-mcp 0.1.0__tar.gz

vectorstep_gateway_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Dalton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vectorstep_gateway_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: vectorstep-gateway-mcp
+Version: 0.1.0
+Summary: MCP server exposing VectorStep Gateway's agent-management and introspection surface to MCP clients (Claude Code/Desktop).
+Author-email: Alex Dalton <alex@vectorstep.io>
+License-Expression: MIT
+Project-URL: Homepage, https://vectorstep.io
+Project-URL: Documentation, https://vectorstep.io/docs/integrations/mcp/
+Project-URL: Changelog, https://vectorstep.io/docs/about/status-and-support/
+Keywords: mcp,vectorstep,ai,agents,gateway,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp==1.28.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Dynamic: license-file
+
+# VectorStep Gateway MCP
+
+An [MCP](https://modelcontextprotocol.io) server that exposes [VectorStep Gateway](https://github.com/bantex01/VectorStep-Gateway) — agent authoring and inspection — to MCP clients such as Claude Code and Claude Desktop.
+
+## What it is
+
+A separate, standalone repository and process with no import-level dependency on the Gateway — the two are coupled only over HTTP, so each can be developed, versioned, and deployed independently.
+
+It lets an MCP client create and edit agents (`agent.yaml` + `soul.md`, with the same validation the gateway itself uses), inspect what's available (configured MCP tool servers and their tools, configured LLM providers), and read gateway health/metrics. Pipelines/steps are not authored here — that's the job of the companion `VectorStep-Service-MCP`; the two have clean, non-overlapping tool sets.
+
+## Quick start
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e .
+```
+
+CI runs this repo's test suite on every push and pull request
+(`.github/workflows/tests.yml`).
+
+Then register it with your MCP client, pointing at a running Gateway instance:
+
+```bash
+claude mcp add vectorstep-gateway \
+  --env GATEWAY_BASE_URL=http://127.0.0.1:18780 \
+  --env GATEWAY_OPERATOR_TOKEN=<your-operator-token> \
+  -- /absolute/path/to/VectorStep-Gateway-MCP/.venv/bin/python -m vectorstep_gateway_mcp
+```
+
+Full install, client config (Claude Code, Claude Desktop, MCP Inspector), and tool inventory: [MCP servers](https://vectorstep.io/docs/integrations/mcp/).
+
+## Documentation
+
+Full docs at [vectorstep.io](https://vectorstep.io/docs/):
+
+| Section | Covers |
+|---|---|
+| [MCP servers](https://vectorstep.io/docs/integrations/mcp/) | Install, client config, tool inventory, write-path design notes for both MCP servers |
+| [Gateway](https://vectorstep.io/docs/gateway/agents/) | Agent authoring (`agent.yaml`, `soul.md`) that this server exposes |
+
+## The ecosystem
+
+| Repo | Role |
+|---|---|
+| **VectorStep** | The orchestration service: webhook intake, pipeline runner, trust gating, UI, analytics |
+| **VectorStep-Gateway** | WebSocket gateway that runs agents: LLM providers, MCP tools, the full agentic loop |
+| **VectorStep-Service-MCP** | MCP server exposing pipeline authoring, run inspection and analytics to Claude Code/Desktop |
+| **VectorStep-Gateway-MCP** | MCP server for authoring and inspecting Gateway agents |
+
+## Licence
+
+VectorStep Gateway MCP is proprietary software, free to download and use under the terms in [`LICENSE`](LICENSE). The source is not publicly distributed and this repository is private.
+
+Bug reports, questions, and feature requests are welcome at **alex@vectorstep.io**. Code contributions are not accepted — see clause 6 of the licence. For a suspected vulnerability, follow [`SECURITY.md`](SECURITY.md) rather than emailing the address above.

vectorstep_gateway_mcp-0.1.0/README.md

@@ -0,0 +1,54 @@
+# VectorStep Gateway MCP
+
+An [MCP](https://modelcontextprotocol.io) server that exposes [VectorStep Gateway](https://github.com/bantex01/VectorStep-Gateway) — agent authoring and inspection — to MCP clients such as Claude Code and Claude Desktop.
+
+## What it is
+
+A separate, standalone repository and process with no import-level dependency on the Gateway — the two are coupled only over HTTP, so each can be developed, versioned, and deployed independently.
+
+It lets an MCP client create and edit agents (`agent.yaml` + `soul.md`, with the same validation the gateway itself uses), inspect what's available (configured MCP tool servers and their tools, configured LLM providers), and read gateway health/metrics. Pipelines/steps are not authored here — that's the job of the companion `VectorStep-Service-MCP`; the two have clean, non-overlapping tool sets.
+
+## Quick start
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e .
+```
+
+CI runs this repo's test suite on every push and pull request
+(`.github/workflows/tests.yml`).
+
+Then register it with your MCP client, pointing at a running Gateway instance:
+
+```bash
+claude mcp add vectorstep-gateway \
+  --env GATEWAY_BASE_URL=http://127.0.0.1:18780 \
+  --env GATEWAY_OPERATOR_TOKEN=<your-operator-token> \
+  -- /absolute/path/to/VectorStep-Gateway-MCP/.venv/bin/python -m vectorstep_gateway_mcp
+```
+
+Full install, client config (Claude Code, Claude Desktop, MCP Inspector), and tool inventory: [MCP servers](https://vectorstep.io/docs/integrations/mcp/).
+
+## Documentation
+
+Full docs at [vectorstep.io](https://vectorstep.io/docs/):
+
+| Section | Covers |
+|---|---|
+| [MCP servers](https://vectorstep.io/docs/integrations/mcp/) | Install, client config, tool inventory, write-path design notes for both MCP servers |
+| [Gateway](https://vectorstep.io/docs/gateway/agents/) | Agent authoring (`agent.yaml`, `soul.md`) that this server exposes |
+
+## The ecosystem
+
+| Repo | Role |
+|---|---|
+| **VectorStep** | The orchestration service: webhook intake, pipeline runner, trust gating, UI, analytics |
+| **VectorStep-Gateway** | WebSocket gateway that runs agents: LLM providers, MCP tools, the full agentic loop |
+| **VectorStep-Service-MCP** | MCP server exposing pipeline authoring, run inspection and analytics to Claude Code/Desktop |
+| **VectorStep-Gateway-MCP** | MCP server for authoring and inspecting Gateway agents |
+
+## Licence
+
+VectorStep Gateway MCP is proprietary software, free to download and use under the terms in [`LICENSE`](LICENSE). The source is not publicly distributed and this repository is private.
+
+Bug reports, questions, and feature requests are welcome at **alex@vectorstep.io**. Code contributions are not accepted — see clause 6 of the licence. For a suspected vulnerability, follow [`SECURITY.md`](SECURITY.md) rather than emailing the address above.

vectorstep_gateway_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "vectorstep-gateway-mcp"
+version = "0.1.0"
+description = "MCP server exposing VectorStep Gateway's agent-management and introspection surface to MCP clients (Claude Code/Desktop)."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Alex Dalton", email = "alex@vectorstep.io" }]
+keywords = ["mcp", "vectorstep", "ai", "agents", "gateway", "llm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: System :: Monitoring",
+]
+dependencies = [
+    "mcp==1.28.1",
+    "httpx>=0.27",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+]
+
+[project.urls]
+Homepage = "https://vectorstep.io"
+Documentation = "https://vectorstep.io/docs/integrations/mcp/"
+Changelog = "https://vectorstep.io/docs/about/status-and-support/"
+
+[project.scripts]
+vectorstep-gateway-mcp = "vectorstep_gateway_mcp.__main__:main"
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+vectorstep_gateway_mcp = ["docs/*.md"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

vectorstep_gateway_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vectorstep_gateway_mcp-0.1.0/src/vectorstep_gateway_mcp/__main__.py

@@ -0,0 +1,13 @@
+"""Entry point for the VectorStep Gateway MCP server. Runs over stdio (Claude Code /
+Desktop) — see the README for GATEWAY_BASE_URL / GATEWAY_OPERATOR_TOKEN configuration."""
+
+from . import tools  # noqa: F401 — importing registers every @mcp.tool()
+from .server import mcp
+
+
+def main() -> None:
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

vectorstep_gateway_mcp-0.1.0/src/vectorstep_gateway_mcp/client.py

@@ -0,0 +1,75 @@
+"""Thin HTTP client for talking to a VectorStep Gateway instance.
+
+This is the ONLY coupling to VectorStep Gateway (SPEC-gateway-mcp.md §2.3): no
+gateway code is imported anywhere in this package. Configured from
+GATEWAY_BASE_URL / GATEWAY_OPERATOR_TOKEN — see the README.
+"""
+
+import os
+
+import httpx
+
+from .errors import GatewayAPIError, error_from_response
+
+
+class GatewayClient:
+    def __init__(
+        self,
+        base_url: str | None = None,
+        token: str | None = None,
+        timeout: float = 30.0,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ):
+        self.base_url = (base_url or os.environ.get("GATEWAY_BASE_URL") or "http://127.0.0.1:18780").rstrip("/")
+        self.token = token if token is not None else os.environ.get("GATEWAY_OPERATOR_TOKEN")
+        self.timeout = timeout
+        # Injectable for tests (httpx.MockTransport) — None uses the real network.
+        self.transport = transport
+
+    def _headers(self) -> dict:
+        return {"Authorization": f"Bearer {self.token}"} if self.token else {}
+
+    async def request(self, method: str, path: str, **kwargs) -> dict:
+        url = f"{self.base_url}{path}"
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout, transport=self.transport) as http_client:
+                resp = await http_client.request(method, url, headers=self._headers(), **kwargs)
+        except httpx.RequestError as exc:
+            raise GatewayAPIError(
+                "network", f"Could not reach VectorStep Gateway at {self.base_url}: {exc}",
+            ) from exc
+
+        if resp.status_code >= 400:
+            raise error_from_response(resp)
+
+        if not resp.content:
+            return {}
+        return resp.json()
+
+    async def get(self, path: str, params: dict | None = None) -> dict:
+        return await self.request("GET", path, params=params)
+
+    async def post(self, path: str, json: dict | None = None) -> dict:
+        return await self.request("POST", path, json=json)
+
+    async def put(self, path: str, json: dict | None = None) -> dict:
+        return await self.request("PUT", path, json=json)
+
+    async def delete(self, path: str) -> dict:
+        return await self.request("DELETE", path)
+
+    async def get_text(self, path: str) -> str:
+        """Like get(), but for endpoints that don't return JSON — currently
+        just /metrics, which is Prometheus exposition text."""
+        url = f"{self.base_url}{path}"
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout, transport=self.transport) as http_client:
+                resp = await http_client.get(url, headers=self._headers())
+        except httpx.RequestError as exc:
+            raise GatewayAPIError(
+                "network", f"Could not reach VectorStep Gateway at {self.base_url}: {exc}",
+            ) from exc
+
+        if resp.status_code >= 400:
+            raise error_from_response(resp)
+        return resp.text

vectorstep_gateway_mcp-0.1.0/src/vectorstep_gateway_mcp/errors.py

@@ -0,0 +1,76 @@
+"""Structured tool-error shape shared by every tool (SPEC-gateway-mcp.md §2.8):
+
+    {"error": {"type": "validation|not_found|collision|upstream|network",
+               "message": "...", "detail": {...}}}
+
+Tools never let an httpx exception or traceback reach the caller — every
+gateway HTTP call goes through GatewayClient, which raises GatewayAPIError;
+tools catch that (via call_safe) and return its .to_dict() as the tool
+result instead of raising.
+"""
+
+from typing import Any
+
+import httpx
+
+_STATUS_TO_TYPE = {
+    400: "validation",
+    404: "not_found",
+    409: "collision",
+}
+
+
+class GatewayAPIError(Exception):
+    def __init__(self, error_type: str, message: str, detail: Any = None):
+        super().__init__(message)
+        self.error_type = error_type
+        self.message = message
+        self.detail = detail if detail is not None else {}
+
+    def to_dict(self) -> dict:
+        return {"error": {"type": self.error_type, "message": self.message, "detail": self.detail}}
+
+
+def error_from_response(resp: httpx.Response) -> GatewayAPIError:
+    """Map an HTTP error response from the gateway to a typed GatewayAPIError.
+
+    FastAPI's HTTPException always serialises to {"detail": <value>}, where
+    <value> is either a plain string (the gateway's older, pre-existing
+    endpoints) or a dict like {"type": "...", "message": "...", ...} for the
+    agent write endpoints (which know their own error type precisely — a
+    plain validation failure vs. a write that references an unconfigured
+    provider/MCP-server can both surface as a 400 with unrelated wording, so
+    status-code/message-sniffing alone can't tell them apart). Prefer that
+    explicit type; fall back to a status-code guess otherwise. Anything
+    unparseable still gets a typed, non-traceback error.
+    """
+    status = resp.status_code
+    try:
+        body = resp.json()
+    except Exception:
+        body = {"raw": resp.text}
+
+    detail = body if isinstance(body, dict) else {"raw": body}
+    inner = detail.get("detail")
+    explicit_type = None
+    if isinstance(inner, str):
+        message = inner
+    elif isinstance(inner, dict):
+        message = inner.get("message") if isinstance(inner.get("message"), str) else None
+        explicit_type = inner.get("type") if isinstance(inner.get("type"), str) else None
+    else:
+        message = None
+    message = message or f"Gateway returned HTTP {status} for {resp.request.method} {resp.request.url.path}"
+
+    error_type = explicit_type or _STATUS_TO_TYPE.get(status, "upstream")
+
+    return GatewayAPIError(error_type, message, detail=detail)
+
+
+async def call_safe(coro) -> dict:
+    """Await `coro`, converting any GatewayAPIError into its structured dict
+    form. Every tool's body should be `return await call_safe(client.get(...))`."""
+    try:
+        return await coro
+    except GatewayAPIError as exc:
+        return exc.to_dict()

vectorstep_gateway_mcp-0.1.0/src/vectorstep_gateway_mcp/server.py

@@ -0,0 +1,9 @@
+"""Shared FastMCP server instance and Gateway client — imported by every tool
+module so they register against the same server (see __main__.py)."""
+
+from mcp.server.fastmcp import FastMCP
+
+from .client import GatewayClient
+
+mcp = FastMCP("vectorstep-gateway")
+client = GatewayClient()

vectorstep_gateway_mcp-0.1.0/src/vectorstep_gateway_mcp/tools/__init__.py

@@ -0,0 +1 @@
+from . import read, write  # noqa: F401 — importing registers every @mcp.tool()

vectorstep_gateway_mcp-0.1.0/src/vectorstep_gateway_mcp/tools/read.py

@@ -0,0 +1,86 @@
+"""Read-only tools (SPEC-gateway-mcp.md §4 "Read tools (Phase A)"). Pure
+GETs (plus the no-write validate_agent dry-run) against the gateway's REST
+API — nothing here mutates agents/ or config.yaml.
+"""
+
+from ..errors import call_safe
+from ..server import client, mcp
+
+
+@mcp.tool()
+async def list_agents() -> dict:
+    """List every agent currently loaded by the gateway: name, model,
+    model_fallbacks, tools (the MCP servers/tool scopes it's wired to), and
+    `version` — a content hash over the agent's ENTIRE config, including
+    soul.md. `version` changes whenever agent.yaml or soul.md changes; VectorStep
+    uses it to scope calibration buckets, so two runs under different
+    `version`s are never pooled as evidence for the same track record. Does
+    not include soul.md content itself — use get_agent(name) for that."""
+    return await call_safe(client.get("/agents"))
+
+
+@mcp.tool()
+async def get_agent(name: str) -> dict:
+    """Get one agent's full definition: parsed config (model, model_fallbacks,
+    max_tokens, tools), the raw agent.yaml text (for round-trip editing), the
+    full soul.md content, and `version` — a content hash over the agent's
+    entire config including soul.md. `version` changes whenever agent.yaml or
+    soul.md changes; VectorStep uses it to scope calibration buckets, so two runs
+    under different `version`s are never pooled as evidence for the same
+    track record. 404 (not_found) if no agent by that name is loaded."""
+    return await call_safe(client.get(f"/agents/{name}"))
+
+
+@mcp.tool()
+async def list_mcp_servers() -> dict:
+    """List the gateway's configured MCP tool servers and their status
+    (running, pid, restart_count). An agent's `tools:` list references these
+    server names — a name here is what create_agent/update_agent's tools:
+    entries must match."""
+    return await call_safe(client.get("/mcp/servers"))
+
+
+@mcp.tool()
+async def list_mcp_tools() -> dict:
+    """List every tool available across all configured MCP servers, grouped
+    by server — name, registered (namespaced) name, description, and JSON
+    input schema for each. Useful for understanding what an agent scoped to
+    a given server can actually do."""
+    return await call_safe(client.get("/mcp/tools"))
+
+
+@mcp.tool()
+async def list_providers() -> dict:
+    """List the gateway's configured LLM providers: name, whether credentials
+    are configured (never the key itself), and the model-string prefix to
+    use when writing an agent's `model`/`model_fallbacks` (e.g.
+    'openrouter/deepseek/deepseek-chat'; a bare model name with no prefix
+    routes to Anthropic by default, so Anthropic's prefix is null). Does NOT
+    enumerate each provider's available model catalogue — only which
+    providers are configured and how to address them."""
+    return await call_safe(client.get("/providers"))
+
+
+async def _metrics_as_dict() -> dict:
+    text = await client.get_text("/metrics")
+    return {"metrics": text}
+
+
+@mcp.tool()
+async def get_metrics() -> dict:
+    """Get the gateway's Prometheus metrics as raw exposition text (agent run
+    counts/durations, token usage, MCP tool call counts, session counts,
+    etc.) under the "metrics" key. This is the same text a Prometheus
+    scraper would pull from /metrics — not pre-aggregated JSON."""
+    return await call_safe(_metrics_as_dict())
+
+
+@mcp.tool()
+async def validate_agent(agent_yaml: str, soul_md: str = "") -> dict:
+    """Validate a candidate agent (agent.yaml + soul.md) against the gateway's
+    real schema AND its reference checks — model/model_fallbacks must map to
+    a configured provider, tools: must reference configured MCP servers —
+    WITHOUT writing anything. Returns {"valid": bool, "errors": [...]}. Use
+    this to iterate before calling create_agent/update_agent; soul_md can be
+    omitted for a quick agent.yaml-only check."""
+    return await call_safe(client.post("/agents/validate", json={"agent_yaml": agent_yaml, "soul_md": soul_md}))

vectorstep_gateway_mcp-0.1.0/src/vectorstep_gateway_mcp/tools/write.py

@@ -0,0 +1,98 @@
+"""Write / action tools (SPEC-gateway-mcp.md §4 "Write / action tools (Phase
+C)"). These mutate the gateway's agents/ directory or trigger a reload —
+unlike tools/read.py, which is pure reads (plus the no-write validate_agent).
+
+Cross-cutting rules enforced here (§6, §9.4):
+  - create_agent never overwrites an existing name unless the caller
+    explicitly passes overwrite=True.
+  - update_agent 404s if the name doesn't exist yet; either agent_yaml or
+    soul_md may be omitted to leave that file untouched.
+  - delete_agent requires the caller to explicitly pass confirm=True —
+    without it, nothing is sent to the gateway at all — and returns the
+    deleted agent.yaml/soul.md so the operation is auditable/recoverable.
+  - agents/ is gitignored (personal to the deployment, unlike VectorStep's
+    git-controlled pipelines/) — every create/update/delete result notes the
+    files were written and reloaded, not that anything was committed.
+  - Secrets: agent.yaml uses '${VAR}' placeholders for anything sensitive —
+    pass them straight through, never resolve/inline a real value. The
+    gateway preserves them verbatim. This server never returns the operator
+    token, a provider API key, or any other config.yaml secret.
+"""
+
+from ..errors import call_safe
+from ..server import client, mcp
+
+
+@mcp.tool()
+async def create_agent(name: str, agent_yaml: str, soul_md: str, overwrite: bool = False) -> dict:
+    """Create a new agent from raw agent.yaml + soul.md text. `name` must
+    match the YAML's own 'name:' field. Fails with a 'collision' error if an
+    agent with that name already exists, unless overwrite=True. Validates
+    schema AND that model/model_fallbacks map to a configured provider and
+    tools: map to configured MCP servers (list_providers/list_mcp_servers
+    show what's available) — on success the files are written and the
+    gateway reloads, but agents/ is gitignored so there is nothing to commit.
+    Consider calling validate_agent first.
+
+    The `version` this agent is assigned (a content hash over its full
+    config — see get_agent) becomes the first entry in its calibration
+    history on the VectorStep side. There's no prior history to reset for a
+    brand-new agent, unlike update_agent below."""
+    return await call_safe(client.post("/agents", json={
+        "name": name, "agent_yaml": agent_yaml, "soul_md": soul_md, "overwrite": overwrite,
+    }))
+
+
+@mcp.tool()
+async def update_agent(name: str, agent_yaml: str | None = None, soul_md: str | None = None) -> dict:
+    """Update an existing agent (404 if 'name' doesn't exist yet). Pass only
+    agent_yaml, only soul_md, or both — an omitted field is left as-is. If
+    agent_yaml is given, its own 'name:' field must still match `name`;
+    renaming an agent is a delete_agent + create_agent, not an update.
+    Written and reloaded on success; agents/ is gitignored so there's
+    nothing to commit.
+
+    IMPORTANT — this changes more than the gateway: editing agent_yaml or
+    soul_md changes this agent's `version` (a content hash over its full
+    config), and VectorStep uses that version to scope calibration buckets. That
+    means this call starts a NEW calibration history in VectorStep for every step
+    that uses this agent — outcomes recorded under the old version stop
+    counting as evidence for the new one. If a step using this agent had
+    `calibration: {enforce: true}` and was passing (a "validated" bucket),
+    it will fall back to its `on_uncalibrated` behaviour (e.g. escalating
+    every run) until enough new labelled runs land under the new version —
+    VectorStep's default threshold is 20. This is not a bug on either side; it's
+    the correct, deliberate consequence of changing what the agent actually
+    does. Point whoever's asking "why did this step start escalating
+    everything" at VectorStep's get_agent_versions(name) tool or its
+    explain("prompt-versions") doc topic to see the history this creates."""
+    body: dict = {}
+    if agent_yaml is not None:
+        body["agent_yaml"] = agent_yaml
+    if soul_md is not None:
+        body["soul_md"] = soul_md
+    return await call_safe(client.put(f"/agents/{name}", json=body))
+
+
+@mcp.tool()
+async def delete_agent(name: str, confirm: bool = False) -> dict:
+    """Permanently delete an agent's agent.yaml + soul.md. Destructive —
+    requires confirm=True or nothing is sent to the gateway at all (a
+    validation error is returned instead). On success returns the deleted
+    agent_yaml/soul_md in the result so the deletion is auditable and
+    recoverable by hand."""
+    if not confirm:
+        return {"error": {"type": "validation",
+                           "message": "delete_agent requires confirm=True — refusing to delete without it.",
+                           "detail": {"name": name}}}
+    return await call_safe(client.delete(f"/agents/{name}"))
+
+
+@mcp.tool()
+async def reload() -> dict:
+    """Re-read all agent.yaml/soul.md files from disk without restarting the
+    gateway. Usually unnecessary — create_agent/update_agent/delete_agent
+    already reload as part of their atomic write — but exposed for the rare
+    case an agent directory was edited outside these tools (e.g. directly on
+    the host) and you want the gateway to pick it up."""
+    return await call_safe(client.post("/reload"))