Skip to main content
hexr.gateway gives your agents access to a curated set of external tools — web search, messaging, weather, and any API you register — without handling API keys in your code. When you invoke a tool, the Gateway validates the arguments, fetches the required API key from Vault using your agent’s SPIFFE identity, and proxies the HTTP request to the external service. Pre-loaded tools are available immediately; you can extend the catalog by registering OpenAPI specifications.

​
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

For explicit configuration, instantiate GatewayClient directly: 
from hexr.gateway import GatewayClient

gateway = GatewayClient(
    tenant="acme-corp",
    timeout=60.0
)
The Gateway endpoint is discovered automatically from the environment set by hexr deploy. You don’t need to provide a URL — the SDK connects to the correct service for your deployment (Cloud or self-hosted).

​
Methods

​
list_tools(tags=None, source=None, force_refresh=False)
method
List available MCP tools. Results are cached for performance.
# 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]
​
get_tool(name)
method
Get a specific tool definition with its parameters and description.
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
​
search_tools(query, limit=10, min_score=0.5)
method
Find tools using semantic search. Useful when you know what you want to do but not the exact tool name.
results = gateway.search_tools("send a message to slack")
for r in results:
    print(f"{r.tool.name} (score: {r.score})")
Returns: list[SearchResult]
​
call_tool(name, arguments=None, timeout=None)
method
Invoke a tool with the given arguments.
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
​
call_tool_mcp(name, arguments=None)
method
Invoke a tool via the raw MCP JSON-RPC 2.0 protocol. Use this when building MCP-compatible integrations.
response = gateway.call_tool_mcp("brave_web_search", {"query": "hexr"})
​
register_openapi(spec, base_url, prefix='')
method
Register tools from an OpenAPI specification. The Gateway converts each operation into a callable tool.
# 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] (registered tool names)

​
Decorators

​
@mcp_tool

Route a function call through the MCP Gateway by name. The function body is ignored — the Gateway handles the actual execution: 
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 methods on a class, filtered by prefix: 
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

1

Agent calls call_tool()

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

Gateway looks up tool definition

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

Fetch credentials from Vault

The Gateway requests the API key for Brave Search from Hexr Vault using its SPIFFE identity.
4

Proxy request to external API

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

Return structured result

Search results are returned to your agent as ToolResult(success=True, result=...).
Agent → Gateway (lookup + validate) → Vault (API key) → External API → ToolResult → Agent

​
Pre-loaded tools

The Gateway ships with tools from three embedded OpenAPI specs. These are available without any registration:
SourceToolsExamples
Brave Search2brave_web_search, brave_local_search
Slack5slack_post_message, slack_list_channels, …
OpenWeatherMap6weather_current, weather_forecast, …
Register additional tools by importing any OpenAPI spec: 
gateway.register_openapi(
    spec="https://api.github.com/openapi.json",
    base_url="https://api.github.com",
    prefix="github"
)