hexgate 0.2.5__tar.gz → 0.2.7__tar.gz

{hexgate-0.2.5 → hexgate-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexgate
-Version: 0.2.5
+Version: 0.2.7
 Summary: Hexgate — authorization infrastructure for AI agents (agent runtime + cloud client).
 License-Expression: MIT
 Requires-Python: >=3.13
@@ -29,6 +29,7 @@ Requires-Dist: litellm>=1.50
 Requires-Dist: openinference-instrumentation-google-adk>=0.1.11
 Requires-Dist: pydantic-ai-slim>=1.88.0
 Requires-Dist: wasmtime>=20.0
+Requires-Dist: mcp>=1.0
 Provides-Extra: dev
 Requires-Dist: ipykernel; extra == "dev"
 Requires-Dist: jupyter; extra == "dev"
@@ -147,11 +148,11 @@ cp .env.sample .env
 hexgate chat --agent example_agent
 ```
 
-Required keys for the example CLI flow:
+Keys the built-in example agent uses (bootstrap no longer hard-requires them — each is only needed if you invoke the piece that reads it):
 
-- `OPENAI_API_KEY`
-- `LINKUP_API_KEY`
-- `TAVILY_API_KEY`
+- `OPENAI_API_KEY` — the default `openai:gpt-5.4` model. Skip it if you pass your own model; if it's missing, the model provider raises a key-named error when the agent is built.
+- `LINKUP_API_KEY` — the built-in `web_search` tool, which raises a clear error the first time it runs without a key.
+- `TAVILY_API_KEY` — the built-in `fetch` tool, same as above.
 
 Run `hexgate --help` to see all subcommands (`chat`, `serve`, `register`), and `hexgate <subcommand> --help` for the flags each one accepts.
 
@@ -175,7 +176,7 @@ The included local agent lives in `examples/example_agent/`, and the CLI can als
 
 The two Quick Starts above aren't competing — they answer different questions.
 
-**Inner loop — `hexgate chat`.** A single-process REPL against a local or builtin agent. No platform, no Docker, no browser. The chat command sets `HEXGATE_LOCAL_MODE=1` automatically so audit stays on your machine even if `HEXGATE_KEY` lives in your `.env` from an earlier session. Denies and approval-required calls render as inline panels in the terminal — same `Decision` data the platform would log, surfaced where you're iterating. Reach for `chat` when you're authoring a policy YAML, tweaking a tool, or shaping a system prompt.
+**Inner loop — `hexgate chat`.** A single-process REPL against a local or builtin agent. No platform, no Docker, no browser. The chat command sets `HEXGATE_LOCAL_MODE=1` automatically so audit stays on your machine even if `HEXGATE_API_KEY` lives in your `.env` from an earlier session. Denies and approval-required calls render as inline panels in the terminal — same `Decision` data the platform would log, surfaced where you're iterating. Reach for `chat` when you're authoring a policy YAML, tweaking a tool, or shaping a system prompt.
 
 **Team loop — `hexgate serve` + dashboard Playground.** Same agent code, but the policy + decisions round-trip through the platform. You get auditable decisions in ClickHouse, the shared Playground UI, and live policy edits via the dashboard. Reach for `serve` when you're collaborating on an agent's behaviour, debugging a production-like trace, or demoing.
 
@@ -203,7 +204,7 @@ make dashboard
 
 # Terminal 3 — mint a token, then serve your local agent
 #   1. Open http://localhost:5173/tokens, click "Mint new token", copy the value.
-#   2. Add to asianf/.env:  HEXGATE_KEY=fty_live_...
+#   2. Add to asianf/.env:  HEXGATE_API_KEY=fty_live_...
 #   3. Pick the agent's Python entrypoint (module:attr — uvicorn-style)
 #      and let `hexgate serve` take over:
 make serve                                          # default — examples.customer_bot:agent
@@ -283,6 +284,22 @@ Integration tests (`pytest -m integration`) round-trip rows through the live Cli
 
 The dashboard's `/policies` page lets you edit each agent's policy. `hexgate serve` re-fetches at every turn boundary, so your edits take effect on the next chat message without a restart.
 
+### Outbound email (Resend)
+
+Verification emails and password-reset links go through [Resend](https://resend.com). The platform API has two senders:
+
+- **Dev (default)** — `StderrEmailSender` prints the mail body (including the magic link) to stderr. No keys needed; click the link out of the terminal to exercise the flow end-to-end.
+- **Production** — `ResendEmailSender`, picked up automatically when both `RESEND_API_KEY` and `HEXGATE_EMAIL_FROM` are set. The from-address must be on a verified Resend domain.
+
+```bash
+# platform/api/.env
+RESEND_API_KEY=re_…
+HEXGATE_EMAIL_FROM="Hexgate <noreply@yourdomain.com>"
+HEXGATE_DASHBOARD_URL=https://app.yourdomain.com   # ← link host inside the email
+```
+
+Partial config (only one var set) keeps the dev stderr sender so an operator notices the misconfig in the startup log line instead of silently failing every send at delivery. Resend API failures are logged at error level but never 5xx the calling endpoint — the user can request a new link.
+
 ## ✨ Core Primitives
 
 The two main primitives are:
@@ -320,7 +337,7 @@ Dev wrote an OpenAI Agents / LangChain / Google ADK / Pydantic AI agent. They wr
 from hexgate.adapters.openai import HexgateRunner   # or .langchain.wrap_langchain_agent, .google.HexgateRunner, .pydantic_ai.wrap_pydantic_agent
 from hexgate.runtime import User
 
-runner = HexgateRunner()                            # picks up HEXGATE_KEY from env
+runner = HexgateRunner()                            # picks up HEXGATE_API_KEY from env
 await runner.run(
     my_agent,
     "refund 30",
@@ -355,8 +372,8 @@ Same enforcement seam, same `User` scope. The difference is whose system of reco
 
 | What dev sets | What changes |
 |---|---|
-| `HEXGATE_KEY=fty_live_<project>_…` | Wakes up the platform path. Without it, adapters / `load_agent` fall back to local / builtin. |
-| `HEXGATE_API_URL=http://localhost:8000` *(optional)* | Platform endpoint. Defaults to localhost. |
+| `HEXGATE_API_KEY=fty_live_<project>_…` | Wakes up the platform path. Without it, adapters / `load_agent` fall back to local / builtin. (Renamed from `HEXGATE_KEY`, which is no longer read.) |
+| `HEXGATE_API_URL=https://app.hexgate.ai` *(optional)* | Platform endpoint. Defaults to Hexgate Cloud (`https://app.hexgate.ai`). Set to `http://localhost:8000` only when self-hosting the platform locally — your key must be minted by whichever platform this points at. |
 | `HEXGATE_LOCAL_POLICY=./policy.yaml` *or* `./bundle/` | Dev escape hatch: enforce a policy from disk, hot-reload on save. Wins over the platform's bundle. |
 | `HEXGATE_BUNDLE_SIGN_KEY_PATH=./keys/dev.private` *(optional)* | Sign locally-recompiled yaml so `bundle.is_signed` reads True. |
 | `HEXGATE_BUNDLE_PUBKEY_PATH=./keys/prod.public` *(optional)* | Verify a pre-built bundle dir against this pubkey on every reload. |
@@ -364,6 +381,11 @@ Same enforcement seam, same `User` scope. The difference is whose system of reco
 
 No config object to instantiate, no `enforce_policy(...)` call to remember on the platform path. The adapter / loader threads it all through.
 
+**Connecting to Hexgate.** The key and the URL are coupled: a `fty_live_…` key only verifies against the platform instance that minted it.
+
+- **Hosted (default):** set `HEXGATE_API_KEY` to the key from [app.hexgate.ai](https://app.hexgate.ai). Leave `HEXGATE_API_URL` unset — it defaults to `https://app.hexgate.ai`.
+- **Self-hosted / local platform:** additionally set `HEXGATE_API_URL=http://localhost:8000` (or your host), and use a key minted by *that* platform.
+
 ### Where enforcement actually happens
 
 Walk through one tool call:
@@ -377,7 +399,7 @@ Walk through one tool call:
 `_policy_source` is set automatically by the loader based on env:
 
 - `HEXGATE_LOCAL_POLICY` set → `YamlPolicySource` or `BundleDirPolicySource` (mtime-driven refresh)
-- `HEXGATE_KEY` set, no local override → `PlatformPolicySource` (ETag / `304 Not Modified` refresh)
+- `HEXGATE_API_KEY` set, no local override → `PlatformPolicySource` (ETag / `304 Not Modified` refresh)
 - Neither → no source attached; enforcement uses whatever was loaded once
 
 **Scope of the per-turn refresh:** only the policy bundle. `system_prompt`, the manifest's tool list, and the model id are read once at agent construction and stay fixed for the lifetime of the process. Edit those on the dashboard and the change lands at the next `hexgate serve` restart — not at the next turn. The split is deliberate: policy is the operator's primary lever (and the one that needs to be auditable per-decision), while the manifest is an author-time concept.
@@ -387,7 +409,7 @@ Walk through one tool call:
 1. **Per-call identity stays explicit.** `User` is the one piece the adapter can't infer from env, because it's per-request, not per-process. One line wrapping each call (`user=User(...)` kwarg on adapters, `async with User(...)` for native).
 2. **`approval_required` tools.** If the policy uses that mode, dev decides what happens — pass `approval_handler=` (True / False / callable) when wrapping. Default for `hexgate serve` is auto-approve; for `hexgate chat` it prompts the TTY. Native code gets whatever the dev wires.
 
-Everything else — fetch, verify, hot-reload, role selection, signature check, decision rendering, tracing — the runtime handles. Set `HEXGATE_KEY` and wrap, or set `HEXGATE_LOCAL_POLICY` and wrap. That's the surface.
+Everything else — fetch, verify, hot-reload, role selection, signature check, decision rendering, tracing — the runtime handles. Set `HEXGATE_API_KEY` and wrap, or set `HEXGATE_LOCAL_POLICY` and wrap. That's the surface.
 
 ## 📦 What You Can Import
 
@@ -430,6 +452,46 @@ from hexgate import (
 )
 ```
 
+## 🔌 MCP servers (proxy)
+
+`hexgate.mcp` wraps any [Model Context Protocol](https://modelcontextprotocol.io) server as a set of LangChain tools that flow through the same policy enforcement, audit, and approval pipeline as native `@agent_tool` functions. Zero glue code — `tools/list` runs at connect time and each exposed tool auto-registers under a `mcp-<server>-<tool>` namespace.
+
+```python
+from hexgate import create_agent, enforce_policy
+from hexgate.mcp import MCPServerConfig, MCPToolset
+
+slack = MCPServerConfig(
+    name="slack", transport="stdio",
+    command="slack-mcp-server",
+    env={"SLACK_TOKEN": "..."},
+)
+
+async with MCPToolset(slack) as mcp:
+    agent, handler = create_agent(model="gpt-5.4", tools=mcp.tools)
+    agent = enforce_policy(agent, "policy.yaml")
+    await agent.ainvoke({"messages": [...]}, config={"configurable": {}})
+```
+
+Then in `policy.yaml` reference the MCP tools by qualified name:
+
+```yaml
+roles:
+  default:
+    tools:
+      "mcp-slack-list_channels": { mode: allow }
+      "mcp-slack-send_message":
+        mode: approval_required
+      "mcp-github-create_issue":
+        mode: allow
+        constraints: ["args.repo == 'hexgate'"]
+```
+
+Hyphens (not colons or dots) because OpenAI Function Calling rejects other separators. Server names must match `^[a-z0-9-]{1,32}$` so qualified names stay under OpenAI's 64-char tool-name limit.
+
+Both transports are supported: **stdio** (`command` + `args` + `env` for subprocess MCP servers) and **streamable HTTP** (`url` + `headers` for remote endpoints). The toolset is an async context manager — opening connects + lists every server's catalog; closing tears down transports symmetrically (with cleanup on partial-open failures).
+
+**Try it:** `make demo-mcp` runs `examples/mcp_demo.py` — one self-contained file that spawns a tiny FastMCP server, attaches it, and walks through one tool call per policy outcome (allow / deny / approval-required). No external services, no LLM key.
+
 ## 🤝 Framework Agent Wrapping
 
 In addition to its native `create_agent(...)` runtime, `hexgate` ships adapters that wrap agents built with **OpenAI Agents SDK**, **LangChain / LangGraph**, **Google ADK**, or **Pydantic AI** to add two things without touching the agent's logic:
@@ -449,7 +511,7 @@ The four integrations differ in shape because the underlying SDKs do:
 
 Role resolution happens **at call time** from the active `User` contextvar — one wrapped agent serves many users concurrently because the scope is per-call. The original agent object is left intact (or, for LangChain BYO-graph tools, mutated by design so the same `tools` list flows through `create_react_agent`); the wrapper holds the policy.
 
-All adapters resolve the API key the same way: from the explicit `api_key=` argument, falling back to the `HEXGATE_KEY` environment variable.
+All adapters resolve the API key the same way: from the explicit `api_key=` argument, falling back to the `HEXGATE_API_KEY` environment variable.
 
 ### OpenAI Agents SDK — `HexgateRunner`
 
@@ -479,7 +541,7 @@ async def main():
         model="gpt-4o-mini",
     )
 
-    runner = HexgateRunner()  # picks up HEXGATE_KEY from env
+    runner = HexgateRunner()  # picks up HEXGATE_API_KEY from env
     result = await runner.run(
         agent,
         "What's the weather in Cherbourg?",
@@ -539,7 +601,7 @@ async def main():
     agent = wrap_langchain_agent(
         agent=graph,
         tools=TOOLS,          # same list passed to create_react_agent — wrapped in place
-        api_key="sk-...",     # or rely on HEXGATE_KEY
+        api_key="sk-...",     # or rely on HEXGATE_API_KEY
     )
 
     result = await agent.ainvoke(
@@ -615,7 +677,7 @@ async def main():
         agent=agent,
         app_name="google_runner_example",
         session_service=session_service,
-    )  # picks up HEXGATE_KEY from env
+    )  # picks up HEXGATE_API_KEY from env
 
     user_msg = types.Content(
         role="user", parts=[types.Part(text="What is the weather in New Delhi?")]
@@ -667,7 +729,7 @@ async def main():
 
     agent = wrap_pydantic_agent(
         agent=agent,
-        api_key="sk-...",  # or rely on HEXGATE_KEY
+        api_key="sk-...",  # or rely on HEXGATE_API_KEY
     )
 
     result = await agent.run(
@@ -1085,13 +1147,12 @@ Worth being explicit about the gaps so operators know where to layer their own c
 
 ## 🔧 Environment
 
-Copy `.env.sample` to `.env` and set:
+Copy `.env.sample` to `.env`. None of these are required to boot — set the ones whose feature you use. A missing key surfaces when that feature runs: the built-in tools raise their own clear error at call time, and the model provider raises a key-named error when the agent is built.
 
-- `OPENAI_API_KEY`
-- `LINKUP_API_KEY`
-- `TAVILY_API_KEY`
-- `LANGFUSE_SECRET_KEY`
-- `LANGFUSE_PUBLIC_KEY`
+- `OPENAI_API_KEY` — default model
+- `LINKUP_API_KEY` — built-in `web_search` tool
+- `TAVILY_API_KEY` — built-in `fetch` tool
+- `LANGFUSE_SECRET_KEY` / `LANGFUSE_PUBLIC_KEY` — tracing (optional)
 - optional `LANGFUSE_HOST`
 
 Policy-bundle enforcement (see [Policy Bundles](#-policy-bundles--compile-sign-enforce-wasm)) reads a few more, all optional:
@@ -1171,7 +1232,7 @@ Register a code-defined agent's manifest with the Hexgate platform. `--agent`
 takes a Python import path of the form `module.path:attribute`, the same shape
 as ASGI/WSGI entrypoints. The CLI imports the module, grabs the agent object,
 and POSTs its manifest to `${HEXGATE_API_URL}/v1/agents` using
-`${HEXGATE_KEY}` as the bearer token:
+`${HEXGATE_API_KEY}` as the bearer token:
 
 ```bash
 hexgate register --agent examples.customer_bot:agent
@@ -1268,7 +1329,7 @@ FastAPI over SQLite. Run with:
 
 ```bash
 cd platform/api
-uv run uvicorn main:app --reload --port 8000
+uv run uvicorn hexgate_api.main:app --reload --port 8000
 ```
 
 The default `support-bot` project is seeded on first boot with two agents — `default` (broad access, side-effects gated by `approval_required`) and `read_only` (everything mutating denied).
@@ -1313,8 +1374,8 @@ Bridges your local agent runtime to the dashboard via the platform's WebSocket r
 
 ```bash
 # in asianf/.env
-HEXGATE_KEY=fty_live_<project>_<biscuit>
-HEXGATE_API_URL=http://localhost:8000       # optional, defaults to localhost:8000
+HEXGATE_API_KEY=fty_live_<project>_<biscuit>
+HEXGATE_API_URL=http://localhost:8000       # optional; only when self-hosting the platform locally
 
 # pick an agent module:attr — uvicorn-style spec
 uv run hexgate serve examples.customer_bot:agent
@@ -1353,7 +1414,7 @@ There's no longer a `HEXGATE_AGENT_NAME` env var, `--agent` flag, or
 `--use` flag — the spec carries everything. If you've been setting
 `HEXGATE_AGENT_NAME` in `.env`, drop it.
 
-### How `load_agent()` resolves with `HEXGATE_KEY`
+### How `load_agent()` resolves with `HEXGATE_API_KEY`
 
 ```python
 from hexgate import load_agent
@@ -1361,8 +1422,8 @@ from hexgate import load_agent
 agent, handler = load_agent("read_only")     # explicit name required
 ```
 
-When `HEXGATE_KEY` is set, `load_agent(name)` fetches the named agent from
-the platform (via `load_hexgate_agent`). When `HEXGATE_KEY` is not set, it
+When `HEXGATE_API_KEY` is set, `load_agent(name)` fetches the named agent from
+the platform (via `load_hexgate_agent`). When `HEXGATE_API_KEY` is not set, it
 falls back to local / registered / builtin resolution — no platform call.
 
 The legacy `HEXGATE_AGENT_NAME` env-var fallback was removed in Phase 7;

{hexgate-0.2.5 → hexgate-0.2.7}/README.md

@@ -107,11 +107,11 @@ cp .env.sample .env
 hexgate chat --agent example_agent
 ```
 
-Required keys for the example CLI flow:
+Keys the built-in example agent uses (bootstrap no longer hard-requires them — each is only needed if you invoke the piece that reads it):
 
-- `OPENAI_API_KEY`
-- `LINKUP_API_KEY`
-- `TAVILY_API_KEY`
+- `OPENAI_API_KEY` — the default `openai:gpt-5.4` model. Skip it if you pass your own model; if it's missing, the model provider raises a key-named error when the agent is built.
+- `LINKUP_API_KEY` — the built-in `web_search` tool, which raises a clear error the first time it runs without a key.
+- `TAVILY_API_KEY` — the built-in `fetch` tool, same as above.
 
 Run `hexgate --help` to see all subcommands (`chat`, `serve`, `register`), and `hexgate <subcommand> --help` for the flags each one accepts.
 
@@ -135,7 +135,7 @@ The included local agent lives in `examples/example_agent/`, and the CLI can als
 
 The two Quick Starts above aren't competing — they answer different questions.
 
-**Inner loop — `hexgate chat`.** A single-process REPL against a local or builtin agent. No platform, no Docker, no browser. The chat command sets `HEXGATE_LOCAL_MODE=1` automatically so audit stays on your machine even if `HEXGATE_KEY` lives in your `.env` from an earlier session. Denies and approval-required calls render as inline panels in the terminal — same `Decision` data the platform would log, surfaced where you're iterating. Reach for `chat` when you're authoring a policy YAML, tweaking a tool, or shaping a system prompt.
+**Inner loop — `hexgate chat`.** A single-process REPL against a local or builtin agent. No platform, no Docker, no browser. The chat command sets `HEXGATE_LOCAL_MODE=1` automatically so audit stays on your machine even if `HEXGATE_API_KEY` lives in your `.env` from an earlier session. Denies and approval-required calls render as inline panels in the terminal — same `Decision` data the platform would log, surfaced where you're iterating. Reach for `chat` when you're authoring a policy YAML, tweaking a tool, or shaping a system prompt.
 
 **Team loop — `hexgate serve` + dashboard Playground.** Same agent code, but the policy + decisions round-trip through the platform. You get auditable decisions in ClickHouse, the shared Playground UI, and live policy edits via the dashboard. Reach for `serve` when you're collaborating on an agent's behaviour, debugging a production-like trace, or demoing.
 
@@ -163,7 +163,7 @@ make dashboard
 
 # Terminal 3 — mint a token, then serve your local agent
 #   1. Open http://localhost:5173/tokens, click "Mint new token", copy the value.
-#   2. Add to asianf/.env:  HEXGATE_KEY=fty_live_...
+#   2. Add to asianf/.env:  HEXGATE_API_KEY=fty_live_...
 #   3. Pick the agent's Python entrypoint (module:attr — uvicorn-style)
 #      and let `hexgate serve` take over:
 make serve                                          # default — examples.customer_bot:agent
@@ -243,6 +243,22 @@ Integration tests (`pytest -m integration`) round-trip rows through the live Cli
 
 The dashboard's `/policies` page lets you edit each agent's policy. `hexgate serve` re-fetches at every turn boundary, so your edits take effect on the next chat message without a restart.
 
+### Outbound email (Resend)
+
+Verification emails and password-reset links go through [Resend](https://resend.com). The platform API has two senders:
+
+- **Dev (default)** — `StderrEmailSender` prints the mail body (including the magic link) to stderr. No keys needed; click the link out of the terminal to exercise the flow end-to-end.
+- **Production** — `ResendEmailSender`, picked up automatically when both `RESEND_API_KEY` and `HEXGATE_EMAIL_FROM` are set. The from-address must be on a verified Resend domain.
+
+```bash
+# platform/api/.env
+RESEND_API_KEY=re_…
+HEXGATE_EMAIL_FROM="Hexgate <noreply@yourdomain.com>"
+HEXGATE_DASHBOARD_URL=https://app.yourdomain.com   # ← link host inside the email
+```
+
+Partial config (only one var set) keeps the dev stderr sender so an operator notices the misconfig in the startup log line instead of silently failing every send at delivery. Resend API failures are logged at error level but never 5xx the calling endpoint — the user can request a new link.
+
 ## ✨ Core Primitives
 
 The two main primitives are:
@@ -280,7 +296,7 @@ Dev wrote an OpenAI Agents / LangChain / Google ADK / Pydantic AI agent. They wr
 from hexgate.adapters.openai import HexgateRunner   # or .langchain.wrap_langchain_agent, .google.HexgateRunner, .pydantic_ai.wrap_pydantic_agent
 from hexgate.runtime import User
 
-runner = HexgateRunner()                            # picks up HEXGATE_KEY from env
+runner = HexgateRunner()                            # picks up HEXGATE_API_KEY from env
 await runner.run(
     my_agent,
     "refund 30",
@@ -315,8 +331,8 @@ Same enforcement seam, same `User` scope. The difference is whose system of reco
 
 | What dev sets | What changes |
 |---|---|
-| `HEXGATE_KEY=fty_live_<project>_…` | Wakes up the platform path. Without it, adapters / `load_agent` fall back to local / builtin. |
-| `HEXGATE_API_URL=http://localhost:8000` *(optional)* | Platform endpoint. Defaults to localhost. |
+| `HEXGATE_API_KEY=fty_live_<project>_…` | Wakes up the platform path. Without it, adapters / `load_agent` fall back to local / builtin. (Renamed from `HEXGATE_KEY`, which is no longer read.) |
+| `HEXGATE_API_URL=https://app.hexgate.ai` *(optional)* | Platform endpoint. Defaults to Hexgate Cloud (`https://app.hexgate.ai`). Set to `http://localhost:8000` only when self-hosting the platform locally — your key must be minted by whichever platform this points at. |
 | `HEXGATE_LOCAL_POLICY=./policy.yaml` *or* `./bundle/` | Dev escape hatch: enforce a policy from disk, hot-reload on save. Wins over the platform's bundle. |
 | `HEXGATE_BUNDLE_SIGN_KEY_PATH=./keys/dev.private` *(optional)* | Sign locally-recompiled yaml so `bundle.is_signed` reads True. |
 | `HEXGATE_BUNDLE_PUBKEY_PATH=./keys/prod.public` *(optional)* | Verify a pre-built bundle dir against this pubkey on every reload. |
@@ -324,6 +340,11 @@ Same enforcement seam, same `User` scope. The difference is whose system of reco
 
 No config object to instantiate, no `enforce_policy(...)` call to remember on the platform path. The adapter / loader threads it all through.
 
+**Connecting to Hexgate.** The key and the URL are coupled: a `fty_live_…` key only verifies against the platform instance that minted it.
+
+- **Hosted (default):** set `HEXGATE_API_KEY` to the key from [app.hexgate.ai](https://app.hexgate.ai). Leave `HEXGATE_API_URL` unset — it defaults to `https://app.hexgate.ai`.
+- **Self-hosted / local platform:** additionally set `HEXGATE_API_URL=http://localhost:8000` (or your host), and use a key minted by *that* platform.
+
 ### Where enforcement actually happens
 
 Walk through one tool call:
@@ -337,7 +358,7 @@ Walk through one tool call:
 `_policy_source` is set automatically by the loader based on env:
 
 - `HEXGATE_LOCAL_POLICY` set → `YamlPolicySource` or `BundleDirPolicySource` (mtime-driven refresh)
-- `HEXGATE_KEY` set, no local override → `PlatformPolicySource` (ETag / `304 Not Modified` refresh)
+- `HEXGATE_API_KEY` set, no local override → `PlatformPolicySource` (ETag / `304 Not Modified` refresh)
 - Neither → no source attached; enforcement uses whatever was loaded once
 
 **Scope of the per-turn refresh:** only the policy bundle. `system_prompt`, the manifest's tool list, and the model id are read once at agent construction and stay fixed for the lifetime of the process. Edit those on the dashboard and the change lands at the next `hexgate serve` restart — not at the next turn. The split is deliberate: policy is the operator's primary lever (and the one that needs to be auditable per-decision), while the manifest is an author-time concept.
@@ -347,7 +368,7 @@ Walk through one tool call:
 1. **Per-call identity stays explicit.** `User` is the one piece the adapter can't infer from env, because it's per-request, not per-process. One line wrapping each call (`user=User(...)` kwarg on adapters, `async with User(...)` for native).
 2. **`approval_required` tools.** If the policy uses that mode, dev decides what happens — pass `approval_handler=` (True / False / callable) when wrapping. Default for `hexgate serve` is auto-approve; for `hexgate chat` it prompts the TTY. Native code gets whatever the dev wires.
 
-Everything else — fetch, verify, hot-reload, role selection, signature check, decision rendering, tracing — the runtime handles. Set `HEXGATE_KEY` and wrap, or set `HEXGATE_LOCAL_POLICY` and wrap. That's the surface.
+Everything else — fetch, verify, hot-reload, role selection, signature check, decision rendering, tracing — the runtime handles. Set `HEXGATE_API_KEY` and wrap, or set `HEXGATE_LOCAL_POLICY` and wrap. That's the surface.
 
 ## 📦 What You Can Import
 
@@ -390,6 +411,46 @@ from hexgate import (
 )
 ```
 
+## 🔌 MCP servers (proxy)
+
+`hexgate.mcp` wraps any [Model Context Protocol](https://modelcontextprotocol.io) server as a set of LangChain tools that flow through the same policy enforcement, audit, and approval pipeline as native `@agent_tool` functions. Zero glue code — `tools/list` runs at connect time and each exposed tool auto-registers under a `mcp-<server>-<tool>` namespace.
+
+```python
+from hexgate import create_agent, enforce_policy
+from hexgate.mcp import MCPServerConfig, MCPToolset
+
+slack = MCPServerConfig(
+    name="slack", transport="stdio",
+    command="slack-mcp-server",
+    env={"SLACK_TOKEN": "..."},
+)
+
+async with MCPToolset(slack) as mcp:
+    agent, handler = create_agent(model="gpt-5.4", tools=mcp.tools)
+    agent = enforce_policy(agent, "policy.yaml")
+    await agent.ainvoke({"messages": [...]}, config={"configurable": {}})
+```
+
+Then in `policy.yaml` reference the MCP tools by qualified name:
+
+```yaml
+roles:
+  default:
+    tools:
+      "mcp-slack-list_channels": { mode: allow }
+      "mcp-slack-send_message":
+        mode: approval_required
+      "mcp-github-create_issue":
+        mode: allow
+        constraints: ["args.repo == 'hexgate'"]
+```
+
+Hyphens (not colons or dots) because OpenAI Function Calling rejects other separators. Server names must match `^[a-z0-9-]{1,32}$` so qualified names stay under OpenAI's 64-char tool-name limit.
+
+Both transports are supported: **stdio** (`command` + `args` + `env` for subprocess MCP servers) and **streamable HTTP** (`url` + `headers` for remote endpoints). The toolset is an async context manager — opening connects + lists every server's catalog; closing tears down transports symmetrically (with cleanup on partial-open failures).
+
+**Try it:** `make demo-mcp` runs `examples/mcp_demo.py` — one self-contained file that spawns a tiny FastMCP server, attaches it, and walks through one tool call per policy outcome (allow / deny / approval-required). No external services, no LLM key.
+
 ## 🤝 Framework Agent Wrapping
 
 In addition to its native `create_agent(...)` runtime, `hexgate` ships adapters that wrap agents built with **OpenAI Agents SDK**, **LangChain / LangGraph**, **Google ADK**, or **Pydantic AI** to add two things without touching the agent's logic:
@@ -409,7 +470,7 @@ The four integrations differ in shape because the underlying SDKs do:
 
 Role resolution happens **at call time** from the active `User` contextvar — one wrapped agent serves many users concurrently because the scope is per-call. The original agent object is left intact (or, for LangChain BYO-graph tools, mutated by design so the same `tools` list flows through `create_react_agent`); the wrapper holds the policy.
 
-All adapters resolve the API key the same way: from the explicit `api_key=` argument, falling back to the `HEXGATE_KEY` environment variable.
+All adapters resolve the API key the same way: from the explicit `api_key=` argument, falling back to the `HEXGATE_API_KEY` environment variable.
 
 ### OpenAI Agents SDK — `HexgateRunner`
 
@@ -439,7 +500,7 @@ async def main():
         model="gpt-4o-mini",
     )
 
-    runner = HexgateRunner()  # picks up HEXGATE_KEY from env
+    runner = HexgateRunner()  # picks up HEXGATE_API_KEY from env
     result = await runner.run(
         agent,
         "What's the weather in Cherbourg?",
@@ -499,7 +560,7 @@ async def main():
     agent = wrap_langchain_agent(
         agent=graph,
         tools=TOOLS,          # same list passed to create_react_agent — wrapped in place
-        api_key="sk-...",     # or rely on HEXGATE_KEY
+        api_key="sk-...",     # or rely on HEXGATE_API_KEY
     )
 
     result = await agent.ainvoke(
@@ -575,7 +636,7 @@ async def main():
         agent=agent,
         app_name="google_runner_example",
         session_service=session_service,
-    )  # picks up HEXGATE_KEY from env
+    )  # picks up HEXGATE_API_KEY from env
 
     user_msg = types.Content(
         role="user", parts=[types.Part(text="What is the weather in New Delhi?")]
@@ -627,7 +688,7 @@ async def main():
 
     agent = wrap_pydantic_agent(
         agent=agent,
-        api_key="sk-...",  # or rely on HEXGATE_KEY
+        api_key="sk-...",  # or rely on HEXGATE_API_KEY
     )
 
     result = await agent.run(
@@ -1045,13 +1106,12 @@ Worth being explicit about the gaps so operators know where to layer their own c
 
 ## 🔧 Environment
 
-Copy `.env.sample` to `.env` and set:
+Copy `.env.sample` to `.env`. None of these are required to boot — set the ones whose feature you use. A missing key surfaces when that feature runs: the built-in tools raise their own clear error at call time, and the model provider raises a key-named error when the agent is built.
 
-- `OPENAI_API_KEY`
-- `LINKUP_API_KEY`
-- `TAVILY_API_KEY`
-- `LANGFUSE_SECRET_KEY`
-- `LANGFUSE_PUBLIC_KEY`
+- `OPENAI_API_KEY` — default model
+- `LINKUP_API_KEY` — built-in `web_search` tool
+- `TAVILY_API_KEY` — built-in `fetch` tool
+- `LANGFUSE_SECRET_KEY` / `LANGFUSE_PUBLIC_KEY` — tracing (optional)
 - optional `LANGFUSE_HOST`
 
 Policy-bundle enforcement (see [Policy Bundles](#-policy-bundles--compile-sign-enforce-wasm)) reads a few more, all optional:
@@ -1131,7 +1191,7 @@ Register a code-defined agent's manifest with the Hexgate platform. `--agent`
 takes a Python import path of the form `module.path:attribute`, the same shape
 as ASGI/WSGI entrypoints. The CLI imports the module, grabs the agent object,
 and POSTs its manifest to `${HEXGATE_API_URL}/v1/agents` using
-`${HEXGATE_KEY}` as the bearer token:
+`${HEXGATE_API_KEY}` as the bearer token:
 
 ```bash
 hexgate register --agent examples.customer_bot:agent
@@ -1228,7 +1288,7 @@ FastAPI over SQLite. Run with:
 
 ```bash
 cd platform/api
-uv run uvicorn main:app --reload --port 8000
+uv run uvicorn hexgate_api.main:app --reload --port 8000
 ```
 
 The default `support-bot` project is seeded on first boot with two agents — `default` (broad access, side-effects gated by `approval_required`) and `read_only` (everything mutating denied).
@@ -1273,8 +1333,8 @@ Bridges your local agent runtime to the dashboard via the platform's WebSocket r
 
 ```bash
 # in asianf/.env
-HEXGATE_KEY=fty_live_<project>_<biscuit>
-HEXGATE_API_URL=http://localhost:8000       # optional, defaults to localhost:8000
+HEXGATE_API_KEY=fty_live_<project>_<biscuit>
+HEXGATE_API_URL=http://localhost:8000       # optional; only when self-hosting the platform locally
 
 # pick an agent module:attr — uvicorn-style spec
 uv run hexgate serve examples.customer_bot:agent
@@ -1313,7 +1373,7 @@ There's no longer a `HEXGATE_AGENT_NAME` env var, `--agent` flag, or
 `--use` flag — the spec carries everything. If you've been setting
 `HEXGATE_AGENT_NAME` in `.env`, drop it.
 
-### How `load_agent()` resolves with `HEXGATE_KEY`
+### How `load_agent()` resolves with `HEXGATE_API_KEY`
 
 ```python
 from hexgate import load_agent
@@ -1321,8 +1381,8 @@ from hexgate import load_agent
 agent, handler = load_agent("read_only")     # explicit name required
 ```
 
-When `HEXGATE_KEY` is set, `load_agent(name)` fetches the named agent from
-the platform (via `load_hexgate_agent`). When `HEXGATE_KEY` is not set, it
+When `HEXGATE_API_KEY` is set, `load_agent(name)` fetches the named agent from
+the platform (via `load_hexgate_agent`). When `HEXGATE_API_KEY` is not set, it
 falls back to local / registered / builtin resolution — no platform call.
 
 The legacy `HEXGATE_AGENT_NAME` env-var fallback was removed in Phase 7;

hexgate-0.2.7/hexgate/adapters/google/mcp.py

@@ -0,0 +1,95 @@
+"""Google ADK adapter for :class:`~hexgate.mcp.MCPToolset`.
+
+Every :class:`~hexgate.mcp.MCPToolProxy` produced by the toolset becomes
+a :class:`google.adk.tools.BaseTool` subclass whose ``_get_declaration``
+returns a ``FunctionDeclaration`` carrying the MCP tool's raw
+JSON Schema (via ``parametersJsonSchema``) and whose ``run_async``
+forwards to the proxy's ``call``. Once wrapped, the resulting tools
+are indistinguishable from ADK-native :class:`FunctionTool` instances
+to the rest of the Google ADK path — attach them to an ``Agent``, then
+wrap via :func:`~hexgate.adapters.google.wrap_google_agent` so the
+existing per-tool policy gate covers MCP invocations too.
+
+Usage::
+
+    from google.adk.agents import Agent
+    from hexgate.adapters.google import wrap_google_agent
+    from hexgate.adapters.google.mcp import wrap_mcp_toolset
+    from hexgate.mcp import MCPServerConfig, MCPToolset
+
+    slack = MCPServerConfig(name="slack", transport="stdio", command="slack-mcp")
+    async with MCPToolset(slack) as mcp:
+        agent = Agent(
+            name="bot",
+            tools=[*wrap_mcp_toolset(mcp), *native],
+        )
+        wrapped, binding = wrap_google_agent(agent, api_key=api_key)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from google.adk.tools import BaseTool
+from google.adk.tools.tool_context import ToolContext
+from google.genai import types as genai_types
+
+from hexgate.mcp.proxy import MCPToolProxy, MCPToolset
+
+
+class _MCPProxyTool(BaseTool):
+    """One :class:`BaseTool` that forwards to an :class:`MCPToolProxy`.
+
+    ADK's :class:`FunctionTool` derives its schema from a Python
+    callable's signature via reflection, which can't express the shapes
+    MCP servers advertise (partial ``required``, ``anyOf`` unions,
+    nested objects with dynamic keys). Subclassing :class:`BaseTool`
+    and returning a hand-built :class:`FunctionDeclaration` from
+    ``_get_declaration`` bypasses the reflection path and hands the
+    server's raw JSON Schema straight to the model — via ADK's
+    ``parametersJsonSchema`` alias which accepts JSON Schema dicts.
+    """
+
+    def __init__(self, proxy: MCPToolProxy) -> None:
+        super().__init__(name=proxy.qualified_name, description=proxy.description)
+        # Store the schema + call as private attrs — ADK's BaseTool has
+        # no field for them, so we ride on the object dict.
+        self._input_schema = proxy.input_schema
+        self._call = proxy.call
+
+    def _get_declaration(self) -> genai_types.FunctionDeclaration:
+        # Gemini's FunctionDeclaration validator rejects any
+        # parametersJsonSchema missing a top-level `type` — literal `{}`,
+        # or a partial like `{"properties": {...}}`, or a bare
+        # `{"anyOf": [...]}`. All three shapes cause the whole tool
+        # list to fail at declaration time, so the agent never gets to
+        # run. Fill in `type: "object"` (the only shape Gemini accepts
+        # for a function-args container) whenever it's absent, and
+        # ensure a `properties` map so the LLM sees an argument surface
+        # rather than an opaque object. LangChain and OpenAI Agents
+        # both tolerate the missing `type` unchanged.
+        schema = self._input_schema if isinstance(self._input_schema, dict) else {}
+        if "type" not in schema:
+            schema = {"type": "object", "properties": {}, **schema}
+        return genai_types.FunctionDeclaration(
+            name=self.name,
+            description=self.description,
+            parametersJsonSchema=schema,
+        )
+
+    async def run_async(
+        self, *, args: dict[str, Any], tool_context: ToolContext
+    ) -> Any:
+        return await self._call(**(args or {}))
+
+
+def wrap_mcp_toolset(toolset: MCPToolset) -> list[BaseTool]:
+    """Wrap every proxy in ``toolset`` as a Google ADK :class:`BaseTool`.
+
+    The returned tools share the toolset's connection lifecycle — they
+    stop working (returning a ``use_after_close`` envelope) once the
+    ``async with MCPToolset(...)`` block exits. Combine with
+    :func:`~hexgate.adapters.google.wrap_google_agent` to gate every
+    invocation through :class:`~hexgate.security.PolicyEnforcer`.
+    """
+    return [_MCPProxyTool(p) for p in toolset.proxies]