> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hybridbox.io/llms.txt
> Use this file to discover all available pages before exploring further.

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

```text theme={null}
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:

```bash theme={null}
curl -i "https://hybridbox.io/.well-known/oauth-protected-resource"
```

Example metadata:

```json theme={null}
{
  "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:

```http theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

```python theme={null}
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.

<Card title="A2A function catalog" icon="list" href="/en/agents/a2a-function-catalog">
  Browse generated function references by domain.
</Card>