# MCP guide

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

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
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
curl -i "https://hybridbox.io/.well-known/oauth-protected-resource"
```

Example metadata:

```json
{
  "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
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
{
  "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
{
  "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
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

[A2A function catalog](/en/agents/a2a-function-catalog)

  Browse generated function references by domain.