MCP guide

Use Hybridbox through the production Model Context Protocol endpoint and code-mode execute tool.

MCP guide

Hybridbox exposes a production Model Context Protocol endpoint at https://hybridbox.io/mcp for MCP clients that want to discover and execute Hybridbox pseudo-functions.

1. Connect to the MCP endpoint

MCP traffic uses JSON-RPC over HTTP POST.

POST https://hybridbox.io/mcp

During initialize, the server advertises MCP capabilities for tool calls.

Supported JSON-RPC methods include:

• initialize
• ping
• notifications/initialized
• tools/list
• tools/call

2. Authenticate the MCP client

MCP clients authenticate with a bearer access token. If a request is missing a valid token, the endpoint returns 401 Unauthorized with a WWW-Authenticate challenge that points to the protected-resource metadata.

Discover the MCP protected resource metadata:

curl -i "https://hybridbox.io/.well-known/oauth-protected-resource"

Example metadata:

{
  "resource": "https://hybridbox.io/mcp",
  "authorization_servers": ["https://auth.hybridbox.io/realms/hybridbox"],
  "audiences": ["hybridbox-mcp"]
}

After the MCP client obtains an access token from the advertised authorization server, send it with each MCP request:

Authorization: Bearer {access_token}

The server also accepts an existing Hybridbox A2A session token as a bearer token, but MCP clients should prefer the OAuth bearer-token flow.

3. List MCP tools

Call tools/list after authentication. The main Hybridbox tools are:

Tool	Purpose
hybridbox_functions_list	List visible pseudo-functions.
hybridbox_functions_explain	Explain one or more visible pseudo-functions.
hybridbox_execute	Execute one or more pseudo-functions with code mode.

4. Execute code with hybridbox_execute

hybridbox_execute takes a required code string and runs one or more Hybridbox pseudo-function calls.

MCP request:

{
  "jsonrpc": "2.0",
  "id": "call-1",
  "method": "tools/call",
  "params": {
    "name": "hybridbox_execute",
    "arguments": {
      "code": "accounts.get(account_id='3c90c3cc-0d44-4b50-8888-8dd25736052a')\naccounts.list(page=1, page_size=25)"
    }
  }
}

MCP response:

{
  "jsonrpc": "2.0",
  "id": "call-1",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"request_id\": \"example\",\n  \"status\": \"completed\",\n  \"result\": {\"last_value\": {\"items\": []}},\n  \"responses\": [{\"index\": 0, \"function\": \"accounts.get\", \"status\": \"completed\", \"result\": {}}, {\"index\": 1, \"function\": \"accounts.list\", \"status\": \"completed\", \"result\": {\"items\": []}}],\n  \"complexity_score\": 2\n}"
      }
    ],
    "isError": false
  }
}

Python-like syntax supported by code mode:

• one function call per line
• variables and expression reuse
• if statements
• for loops
• range(...)
• sequential execution in source order

account = accounts.get(account_id="3c90c3cc-0d44-4b50-8888-8dd25736052a")
if auth.whoami()["authenticated"]:
    domains.list(page=1, page_size=10)
for page in range(1, 4):
    accounts.list(page=page, page_size=25)

The wrapped execution response includes responses[] for every function call and result.last_value for the final successful call.

Function catalog

Open the function catalog when you need callable names, compact signatures, arguments, return fields, auth metadata, and public API route mappings.

A2A function catalog

Browse generated function references by domain.