hexr.gateway

Quick Start

import hexr.gateway

# List available tools
tools = hexr.gateway.list_tools()
for tool in tools:
    print(f"{tool.name}: {tool.description}")

# Call a tool
result = hexr.gateway.call_tool("brave_web_search", {"query": "hexr platform"})
print(result.result)

GatewayClient

from hexr.gateway import GatewayClient

gateway = GatewayClient(
    base_url="http://hexr-gateway.hexr-system:8090",
    tenant="acme-corp",
    timeout=60.0
)

Methods

method

List available MCP tools. Results are cached.

# All tools
tools = gateway.list_tools()

# Filter by tag
search_tools = gateway.list_tools(tags=["search"])

# Force refresh cache
tools = gateway.list_tools(force_refresh=True)

Returns: list[Tool]

method

Get a specific tool definition.

tool = gateway.get_tool("brave_web_search")
print(tool.name)        # "brave_web_search"
print(tool.description) # "Search the web using Brave Search API"
print(tool.parameters)  # [ToolParameter(...), ...]

Returns: Tool

method

Semantic search for tools.

results = gateway.search_tools("send a message to slack")
for r in results:
    print(f"{r.tool.name} (score: {r.score})")

Returns: list[SearchResult]

method

Invoke a tool.

result = gateway.call_tool(
    "brave_web_search",
    {"query": "latest AI research", "count": 5}
)
if result.success:
    print(result.result)
else:
    print(f"Error: {result.error}")

Returns: ToolResult

method

Invoke via raw MCP JSON-RPC 2.0 protocol.

response = gateway.call_tool_mcp("brave_web_search", {"query": "hexr"})

method

# Register from URL
tools = gateway.register_openapi(
    spec="https://api.example.com/openapi.json",
    base_url="https://api.example.com",
    prefix="example"
)
print(f"Registered {len(tools)} tools")

Returns: list[str] (tool names)

Decorators

@mcp_tool

Route a function call through the MCP Gateway:

from hexr.gateway import mcp_tool

@mcp_tool("brave_web_search")
def search(query: str) -> str:
    pass  # Gateway handles the actual call

result = search("hexr platform")

@discover_tools

Auto-bind gateway tools as class methods:

from hexr.gateway import discover_tools

@discover_tools(prefix="brave")
class SearchAgent:
    pass

agent = SearchAgent()
result = agent.brave_web_search(query="hexr")  # Auto-bound method

Tool Types

from hexr.gateway import Tool, ToolParameter, ToolResult, ToolType

# Tool definition
tool = Tool(
    name="brave_web_search",
    description="Search the web",
    parameters=[
        ToolParameter(name="query", type="string", required=True),
        ToolParameter(name="count", type="integer", default=10)
    ],
    source="openapi",
    tool_type=ToolType.FUNCTION
)

# Convert to LLM-compatible formats
openai_format = tool.to_openai_format()
mcp_format = tool.to_mcp_format()

How It Works

Agent calls call_tool()

Your agent calls call_tool("brave_web_search", {query: "..."}) via the Gateway SDK.

Gateway looks up tool definition

The Gateway resolves the tool name to its registered definition and validates the arguments against the parameter schema.

Fetch credentials from Vault

The Gateway requests the API key for Brave Search from Hexr Vault (SPIFFE-authenticated).

Proxy request to external API

The Gateway sends GET /search?q=... to the Brave API with the injected API key header.

Return structured result

Search results are returned to the agent as ToolResult(success=true, result=...).

Agent → Gateway (lookup + validate) → Vault (API key) → External API → ToolResult → Agent

The Gateway:

Validates arguments against the tool’s parameter schema
Injects credentials from Hexr Vault (no API keys in your code)
Proxies the HTTP request to the external API
Returns the result as a structured ToolResult

Pre-Loaded Tools

The Gateway ships with tools from 3 embedded OpenAPI specs:

Source	Tools	Examples
Brave Search	2	`brave_web_search`, `brave_local_search`
Slack	5	`slack_post_message`, `slack_list_channels`, …
OpenWeatherMap	6	`weather_current`, `weather_forecast`, …

gateway.register_openapi(
    spec="https://api.github.com/openapi.json",
    base_url="https://api.github.com",
    prefix="github"
)

SDK Overview

Decorators & Functions

Modules

hexr.gateway

Quick Start

GatewayClient

Methods

Decorators

@mcp_tool

@discover_tools

Tool Types

How It Works

Pre-Loaded Tools

​Quick Start

​GatewayClient

​Methods

​Decorators

​@mcp_tool

​@discover_tools

​Tool Types

​How It Works

​Pre-Loaded Tools

Quick Start

GatewayClient

Methods

Decorators

@mcp_tool

@discover_tools

Tool Types

How It Works

Pre-Loaded Tools