MCP servers (proxy)

Hexgate’s hexgate.mcp module wraps any MCP server as framework-native tool objects so they go through the same policy enforcement, audit, and approval flow as native tool functions. Zero glue code: connect the server, every tool it exposes auto-registers under a mcp-<server>-<tool> namespace. Wire the tools through whichever adapter your agent is built on (LangChain, OpenAI Agents, Pydantic AI, Google ADK).

Usage

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": {}})

Tool naming

Qualified name format: mcp-<server>-<tool>. Hyphens (not colons or dots) so the name passes OpenAI Function Calling’s regex ^[a-zA-Z0-9_-]{1,64}$. The server name is caller-supplied and validated against ^[a-z0-9-]{1,32}$ so qualified names stay under the 64-char OpenAI limit even for medium-long MCP tool names. Reference MCP tools in policy.yaml by their qualified names:

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"']

Transports

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).

Adapter coverage

MCPToolset produces framework-agnostic MCPToolProxy descriptors. Each adapter has a wrap_mcp_toolset that turns those into its own tool type. Same shape everywhere; pick the one that matches your agent.

# LangChain (also the back-compat default via mcp.tools)
from hexgate.adapters.langchain.mcp import wrap_mcp_toolset
tools = wrap_mcp_toolset(mcp)  # list[langchain_core.tools.BaseTool]

# OpenAI Agents
from hexgate.adapters.openai.mcp import wrap_mcp_toolset
tools = wrap_mcp_toolset(mcp)  # list[agents.FunctionTool]

# Pydantic AI
from hexgate.adapters.pydantic_ai.mcp import wrap_mcp_toolset
tools = wrap_mcp_toolset(mcp)  # list[pydantic_ai.tools.Tool]

# Google ADK
from hexgate.adapters.google.mcp import wrap_mcp_toolset
tools = wrap_mcp_toolset(mcp)  # list[google.adk.tools.BaseTool]

Every wrapped tool carries the qualified name, the MCP-advertised description and JSON Schema, and the same {"ok": True | False, ...} envelope on invocation. The tools share the toolset’s connection lifecycle: once the async with MCPToolset(...) block exits, calls return a use_after_close envelope rather than crashing.

Try it

Two self-contained demos — both spawn a tiny FastMCP server, so there are no external services and no LLM key required. A quick one-shot run:

make demo-mcp

Runs examples/mcp_demo.py — attaches the server via MCPToolset and prints one call per policy outcome (allow / deny / approval-required). An interactive notebook:

marimo edit deploy/mcp_gate_demo.py

Runs deploy/mcp_gate_demo.py — a marimo notebook that connects to the server, lists its tools under the mcp-<server>-<tool> namespace, and gates them with a default-deny policy plus per-argument constraints. Edit the tool and arguments and re-run to watch the gate decide live: allowed calls execute against the server, denied ones are stopped before it.

What hexgate does NOT do (yet)

Catalog threat scanning — typosquatting and prompt-injection pattern detection on tool descriptions at registration time is not performed.
Response-side gating — gating based on the return value of an MCP call. Today only the invocation is gated; returned content is passed through to the model.
Reconnection — a dropped transport surfaces as a tool-call error; the toolset doesn’t auto-reconnect.
Declarative mcp_servers: block in agent.yaml — attach servers programmatically via MCPToolset(...); there’s no YAML wiring yet.

Get started

Concepts

Framework adapters

Policy

CLI

MCP servers (proxy)

Usage

Tool naming

Transports

Adapter coverage

Try it

What hexgate does NOT do (yet)

​Usage

​Tool naming

​Transports

​Adapter coverage

​Try it

​What hexgate does NOT do (yet)

Usage

Tool naming

Transports

Adapter coverage

Try it

What hexgate does NOT do (yet)