Titan MCP Server Developer Documentation

Quick start

1. Configure your MCP client

Use a Titan API key provided for your account. Keep the key inside a trusted agent runtime or backend service, never in browser-side code.

MCP client configuration

{
  "mcpServers": {
    "titan": {
      "url": "https://mcp.project-titan.com/mcp",
      "headers": {
        "Authorization": "Bearer ${TITAN_API_KEY}",
        "X-MCP-Client-ID": "client-agent"
      }
    }
  }
}

Authentication

Preferred header: Authorization: Bearer <TITAN_API_KEY>. Alternative: X-API-KEY.

Tenant scope

Every tool requires tenant_id. It must match the account attached to the API key.

Transport

Use MCP JSON-RPC over HTTPS. Responses are returned as text/event-stream.

Protocol smoke tests

2. Verify connectivity

Initialize MCP session

curl -i https://mcp.project-titan.com/mcp \
  -H "Authorization: Bearer <TITAN_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {
        "name": "client-agent",
        "version": "1.0.0"
      }
    }
  }'

List Titan tools

curl -i https://mcp.project-titan.com/mcp \
  -H "Authorization: Bearer <TITAN_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  --data '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

Tool catalog

Available read-only tools

`search_competitor_rates`

Searches hotel competitor rates for a destination, property, or comp set over a stay window.

Inputs: tenant, destination or property, check-in/out, adults, currency, optional competitor ids.
Output: normalized rates, property name, source, room type, meal plan, cancellation policy, fetched timestamp.

`get_market_demand`

Returns daily or weekly market demand signals for a tenant-owned destination.

Inputs: tenant, destination, date range, granularity.
Output: demand score, occupancy signal, ADR signal, confidence, explanation.

`get_destination_events`

Returns events, holidays, and other demand drivers for a destination.

Inputs: tenant, destination, date range, optional event types.
Output: event name, type, dates, venue, estimated impact, source, confidence.

`get_short_term_rental_market`

Returns short-term-rental market intelligence when persisted STR data is available.

Inputs: tenant, destination, date range, optional bedroom count and property type.
Output: availability flag, active listings, occupancy, ADR, RevPAR, changes, confidence.

`compare_hotel_vs_str_demand`

Compares hotel demand signals with STR demand signals for a tenant-owned destination.

Inputs: tenant, destination, date range.
Output: hotel demand score, STR demand score, demand gap, drivers, summary.

`explain_rate_opportunity`

Explains whether a property should increase, decrease, or hold rates over a date range.

Inputs: tenant, property, date range, signal inclusion flags.
Output: recommendation, confidence, reasoning, supporting signals, risks, next steps.

Examples

Call Titan tools

Replace placeholders with the tenant, destination, and property ids provided for your Titan account.

Market demand

curl -i https://mcp.project-titan.com/mcp \
  -H "Authorization: Bearer <TITAN_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  --data '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_market_demand",
      "arguments": {
        "tenant_id": <TENANT_ID>,
        "destination_id": <DESTINATION_ID>,
        "start_date": "2026-06-01",
        "end_date": "2026-06-30",
        "granularity": "daily"
      }
    }
  }'

Competitor rates

curl -i https://mcp.project-titan.com/mcp \
  -H "Authorization: Bearer <TITAN_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  --data '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "search_competitor_rates",
      "arguments": {
        "tenant_id": <TENANT_ID>,
        "property_id": null,
        "destination_id": <DESTINATION_ID>,
        "check_in": "2026-06-12",
        "check_out": "2026-06-15",
        "adults": 2,
        "children": null,
        "currency": "EUR",
        "competitor_ids": null
      }
    }
  }'

Rate opportunity

curl -i https://mcp.project-titan.com/mcp \
  -H "Authorization: Bearer <TITAN_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  --data '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "explain_rate_opportunity",
      "arguments": {
        "tenant_id": <TENANT_ID>,
        "property_id": <PROPERTY_ID>,
        "start_date": "2026-06-01",
        "end_date": "2026-06-30",
        "include_competitors": true,
        "include_events": true,
        "include_str_market": true
      }
    }
  }'

Security and limits

Safe integration rules

Tenant isolation

The API key account must match tenant_id. Hotel and destination access is checked before data is returned.

Read-only scope

Titan MCP v1 exposes read-only tools only. No write, update, or delete actions are available.

Date ranges

The default maximum date range is 90 days. Split larger analysis windows into smaller calls.

Rate limits

The default rate limit is 60 requests per minute per tenant and client partition.

Troubleshooting

Common responses

Status	Meaning	Action
`401`	Missing or invalid Titan MCP API key.	Check the auth header and API key status.
`403`	The client or tenant is not allowed.	Check `X-MCP-Client-ID` and tenant access.
`405`	The endpoint was called with the wrong HTTP method.	Use `POST` for MCP JSON-RPC calls.
`429`	Rate limit exceeded.	Wait and retry with backoff.