MCP Overview

Audience: developers building LLM-driven integrations on top of Hostex, and the LLM agents that read this page directly. Every Hostex OpenAPI v3 endpoint that touches operational data is also exposed as a Model Context Protocol (MCP) tool, so an MCP-aware client can drive Hostex end-to-end through natural language with no glue code.

TL;DR

mcp_endpoint:         https://hostex.io/mcp
transport:            streamable-http      # MCP HTTP transport, JSON-RPC over text/event-stream
auth:
  bearer_token:       https://hostex.io/app/api/open-api   # create token, send as Authorization: Bearer …
  oauth:              auto-discovery       # RFC 9728 + 8414 + 7591 chain from the endpoint
tools:
  total:              72
  read_only:          27                   # any access token can call these
  writable:           45                   # require a writable access token
  requires_confirm:   31                   # subset of writable, clients should prompt the user
categories:           [reservation, property, calendar, finance, task,
                       knowledge_base, messaging, automation, meta]
ai_friendly_surface:
  site_index:         https://api-doc.hostex.io/llms.txt
  raw_markdown:       https://api-doc.hostex.io/reference/{slug}.md   # any page; e.g. mcp-overview.md
  openapi_spec:       https://api.hostex.io/v3/config.json           # whole spec, includes x-mcp blocks
  tools_catalog:      https://api-doc.hostex.io/reference/mcp-tools-reference.md

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

Machine-readable surface (for AI agents reading this page)

Hostex publishes a few canonical artifacts that an agent can ingest without scraping HTML:

The MCP discovery chain (below) is itself machine-readable and follows public RFCs, so an agent can bootstrap connectivity from just the https://hostex.io/mcp URL.

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 — 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 Code, 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). For programmatic ingestion fetch https://api-doc.hostex.io/reference/mcp-tools-reference.md.

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 Code, Codex, Claude Desktop, Cursor, and mcp-inspector.
• Browse the catalog: Tools Reference — every tool with parameters, since-version, and example phrases.
• OAuth details: Authorization Workflow — what's happening when your MCP client OAuths in.
• Feed an agent the whole site: llms.txt — every page indexed in one file, ready to paste into a context window or pipeline.