MCP Overview

Every Hostex OpenAPI v3 endpoint that mutates or queries operational data is also exposed as a Model Context Protocol (MCP) tool. Any MCP-aware LLM client — Claude Desktop, Cursor, mcp-inspector, an in-house agent — can drive Hostex end-to-end through natural language, with no glue code.

If you are not building an LLM integration you can ignore this section and use the REST endpoints. Both surfaces share the same authentication, scopes, rate limits, and audit log.

Why MCP

MCP is an open protocol that standardizes how a model discovers and invokes external tools. A single HTTP endpoint speaks JSON-RPC both ways, and the client gets:

• A typed tool catalog (name, description, JSON-schema parameters, side-effect markers).
• Streaming progress for long-running calls.
• Per-tool intent examples ("call this when the user says X").
• A standard OAuth 2.1 + PKCE flow with full discovery, so end users authenticate once in their browser and the client never sees their password.

Hostex's MCP layer adds the following on top of every exposed v3 endpoint:

These live in the OpenAPI spec under each operation's x-mcp block, so REST consumers see no change.

Endpoint

https://hostex.io/mcp

The server speaks the Streamable HTTP transport (the current MCP HTTP variant). A POST returns JSON-RPC over a text/event-stream response; a GET or unauthenticated request returns a WWW-Authenticate: Bearer realm="...", resource_metadata="https://hostex.io/.well-known/oauth-protected-resource/mcp" header so MCP clients discover the OAuth flow automatically (RFC 9728).

Discovery endpoints

Standard MCP clients only need to know https://hostex.io/mcp. They then read:

You normally do not call any of these yourself — Claude Desktop, Cursor, mcp-inspector, the official SDKs and so on do it transparently. See MCP Quickstart for concrete client setup.

Authentication

Two equivalent paths to a Bearer token:

OAuth runs as a public client with PKCE (no client secret). The discovered authorization endpoint is the Host Portal's consent page; the token endpoint is POST https://api.hostex.io/v3/oauth/authorizations; revoke is POST https://api.hostex.io/v3/oauth/revoke. See OAuth Authorization Workflow for full request/response details.

Scope semantics

Tools inherit the scope of the access token used:

A writable token is required for any tool that creates, updates, deletes, sends a message, or otherwise mutates state. 31 of the writable tools also carry requires_confirmation: true so clients can surface a "are you sure?" prompt for irreversible operations.

What's exposed

72 tools in total, all derived from operations where x-mcp.exposed: true is set in the OpenAPI spec (https://api.hostex.io/v3/config.json). Distribution by category:

The full catalog, including each tool's parameters and example phrases, lives in the Tools Reference (regenerated from the spec — always current).

What's not exposed

• OAuth endpoints themselves (/oauth/*) — the client handles OAuth, no point exposing it as a tool.
• Webhook configuration (/webhooks/*) — infrastructure setup belongs in the dashboard, not the LLM.
• Channel credentials and other operator-private setup.

The MCP server is a thin shim over the v3 REST API — no extra logic, validation, or rate-limit window on top. A tool call hits the same controller as the equivalent REST call, returns the same JSON, and counts against the same per-token quota.

What a tool call looks like

Once authenticated, an MCP tools/call for search_reservations becomes (after the client serializes it):

POST /mcp HTTP/1.1
Host: hostex.io
Authorization: Bearer <access_token>
Content-Type: application/json
Accept: text/event-stream

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_reservations",
    "arguments": {
      "start_check_in_date": "2026-06-01",
      "end_check_in_date":   "2026-06-08",
      "status":              "accepted"
    }
  }
}

The response is an event stream whose final data: line carries:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"request_id\":\"...\",\"data\":{\"reservations\":[ ... ]}}"
      }
    ],
    "isError": false
  }
}

The inner text is exactly what GET /reservations would return — the dispatcher does not reshape responses.

If the v3 controller returns a non-2xx (validation error, missing scope, throttle, etc.), the JSON-RPC reply carries isError: true and the error body so the LLM can decide how to handle or surface it.

REST vs MCP — when to use which

Both surfaces sit on the same data and the same access token, so it is normal to use them side by side — REST for your backend and MCP for your AI assistant.

Audit

Every MCP tool call is logged the same way a REST call is — same request_id, same per-token line in the operator activity log, same response timing. Confirmation prompts happen client-side (the server stays neutral and trusts whatever the user approved). If you need a server-side approval workflow, gate the action on your side before invoking the tool.

Where to go next

• Connect a client: MCP Quickstart — copy-pasteable configs for Claude Desktop, Cursor, and mcp-inspector.
• Browse the catalog: Tools Reference — all 72 tools with parameters and example phrases.
• OAuth details: Authorization Workflow — full request/response if you're building a custom client.