hexgate 0.2.4__tar.gz → 0.2.6__tar.gz

{hexgate-0.2.4 → hexgate-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexgate
-Version: 0.2.4
+Version: 0.2.6
 Summary: Hexgate — authorization infrastructure for AI agents (agent runtime + cloud client).
 License-Expression: MIT
 Requires-Python: >=3.13
@@ -29,11 +29,13 @@ 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"
 Requires-Dist: pytest>=8.4.1; extra == "dev"
 Requires-Dist: pytest-asyncio>=1.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
 Requires-Dist: ruff>=0.12.2; extra == "dev"
 Dynamic: license-file
 
@@ -50,6 +52,7 @@ Policy enforcement, signed policy bundles, per-request user scope, audit trail
 
 [![PyPI](https://img.shields.io/pypi/v/hexgate?color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/hexgate/)
 [![CI](https://github.com/HexamindOrganisation/hexgate/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/HexamindOrganisation/hexgate/actions/workflows/tests.yml)
+[![codecov](https://codecov.io/gh/HexamindOrganisation/hexgate/branch/main/graph/badge.svg?flag=sdk)](https://codecov.io/gh/HexamindOrganisation/hexgate)
 [![Downloads](https://img.shields.io/pypi/dm/hexgate?color=blueviolet)](https://pypi.org/project/hexgate/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
@@ -145,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.
 
@@ -173,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.
 
@@ -201,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
@@ -281,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:
@@ -318,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",
@@ -353,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. |
@@ -362,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:
@@ -375,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.
@@ -385,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
 
@@ -428,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:
@@ -447,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`
 
@@ -477,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?",
@@ -537,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(
@@ -613,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?")]
@@ -665,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(
@@ -1083,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:
@@ -1169,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
@@ -1311,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
@@ -1351,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
@@ -1359,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.4 → hexgate-0.2.6}/README.md

@@ -11,6 +11,7 @@ Policy enforcement, signed policy bundles, per-request user scope, audit trail
 
 [![PyPI](https://img.shields.io/pypi/v/hexgate?color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/hexgate/)
 [![CI](https://github.com/HexamindOrganisation/hexgate/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/HexamindOrganisation/hexgate/actions/workflows/tests.yml)
+[![codecov](https://codecov.io/gh/HexamindOrganisation/hexgate/branch/main/graph/badge.svg?flag=sdk)](https://codecov.io/gh/HexamindOrganisation/hexgate)
 [![Downloads](https://img.shields.io/pypi/dm/hexgate?color=blueviolet)](https://pypi.org/project/hexgate/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
@@ -106,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.
 
@@ -134,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.
 
@@ -162,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
@@ -242,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:
@@ -279,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",
@@ -314,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. |
@@ -323,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:
@@ -336,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.
@@ -346,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
 
@@ -389,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:
@@ -408,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`
 
@@ -438,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?",
@@ -498,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(
@@ -574,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?")]
@@ -626,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(
@@ -1044,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:
@@ -1130,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
@@ -1272,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
@@ -1312,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
@@ -1320,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.4 → hexgate-0.2.6}/hexgate/adapters/google/runner.py

@@ -4,7 +4,6 @@ active role. Langfuse propagation mirrors User identity into spans.
 """
 
 import asyncio
-import os
 from contextlib import contextmanager
 from typing import Any, AsyncGenerator, Generator
 
@@ -17,6 +16,7 @@ from langfuse import get_client, propagate_attributes
 from openinference.instrumentation.google_adk import GoogleADKInstrumentor
 
 from hexgate.adapters.google.wrapper import wrap_google_agent
+from hexgate.config.env import resolve_api_key
 from hexgate.runtime import User
 
 
@@ -32,10 +32,10 @@ class HexgateRunner:
         api_key: str | None = None,
         **runner_kwargs: Any,
     ):
-        self.api_key = api_key or os.getenv("HEXGATE_KEY")
+        self.api_key = resolve_api_key(api_key)
         if self.api_key is None:
             raise ValueError(
-                "HEXGATE_KEY is not set. Pass api_key= explicitly or set HEXGATE_KEY environment variable."
+                "HEXGATE_API_KEY is not set. Pass api_key= explicitly or set the HEXGATE_API_KEY environment variable."
             )
         # Policy resolves at construction (the loud-failure point); the
         # Runner is built once — refresh swaps the enforcer's policy

{hexgate-0.2.4 → hexgate-0.2.6}/hexgate/adapters/langchain/wrapper.py

@@ -11,13 +11,12 @@ proxy at the top of every call.
 
 from __future__ import annotations
 
-import os
-
 from langchain_core.tools import BaseTool
 from langgraph.graph.state import CompiledStateGraph
 
 from hexgate.adapters.langchain.agent import HexgateLangchainAgent
 from hexgate.adapters.langchain.tools import install_enforcer_on_tools
+from hexgate.config.env import resolve_api_key
 from hexgate.security.binding import PolicyBinding, resolve_policy
 from hexgate.security.enforcer import build_enforcer
 
@@ -33,14 +32,14 @@ def wrap_langchain_agent(
     Mutates ``tools`` in place so the graph keeps its references.
     The returned proxy takes ``user`` per invocation; role resolves at
     call time from the active :class:`User`. ``api_key`` falls back to
-    ``HEXGATE_KEY``. ``NEEDS_APPROVAL`` outcomes render as structured
+    ``HEXGATE_API_KEY``. ``NEEDS_APPROVAL`` outcomes render as structured
     errors — wire any host-side approval flow outside the SDK. The
     enforced policy is the platform's; unlisted tools are denied.
     """
-    resolved_key = api_key if api_key else os.getenv("HEXGATE_KEY")
+    resolved_key = resolve_api_key(api_key)
     if not resolved_key:
         raise ValueError(
-            "No API key provided. Pass api_key= explicitly or set HEXGATE_KEY environment variable."
+            "No API key provided. Pass api_key= explicitly or set the HEXGATE_API_KEY environment variable."
         )
 
     agent_name = getattr(agent, "name", "default")

{hexgate-0.2.4 → hexgate-0.2.6}/hexgate/adapters/openai/runner.py

@@ -8,7 +8,6 @@ enforcer, so a refresh swap reaches every clone.
 """
 
 import asyncio
-import os
 from contextlib import contextmanager
 
 import nest_asyncio
@@ -26,6 +25,7 @@ from langfuse import get_client, propagate_attributes
 from openinference.instrumentation.openai_agents import OpenAIAgentsInstrumentor
 
 from hexgate.adapters.openai.wrapper import wrap_openai_agent
+from hexgate.config.env import resolve_api_key
 from hexgate.runtime import User
 from hexgate.security.binding import PolicyBinding, resolve_policy
 from hexgate.security.enforcer import build_enforcer
@@ -35,10 +35,10 @@ class HexgateRunner:
     """Runner for OpenAI agents with Hexgate tool policy and observability."""
 
     def __init__(self, api_key: str | None = None):
-        self.api_key = api_key or os.getenv("HEXGATE_KEY")
+        self.api_key = resolve_api_key(api_key)
         if self.api_key is None:
             raise ValueError(
-                "HEXGATE_KEY is not set. Pass api_key= explicitly or set HEXGATE_KEY environment variable."
+                "HEXGATE_API_KEY is not set. Pass api_key= explicitly or set the HEXGATE_API_KEY environment variable."
             )
         # Cached per agent name — keeps the ETag memory alive across runs.
         self._bindings: dict[str, PolicyBinding] = {}