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

Business tools can omit tenant_id. Titan defaults it to 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": {}
  }'

Discover account context

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": "whoami",
      "arguments": {}
    }
  }'

Tool catalog

Available read-only tools

`whoami`

Returns the authenticated tenant context for the current API key.

Inputs: none.
Output: tenant id, account name, client id, currency, limits, destination count, property count.

`list_destinations`

Lists destination ids authorized for the current API key.

Inputs: none.
Output: destination id, name, source, total hotels, latest demand snapshot date.

`list_properties`

Lists own and authorized property ids for rate and opportunity tools.

Inputs: none.
Output: property id, name, city, country, own-property flag.

`get_revenue_manager_context`

First-call tool for revenue-manager conversations.

Inputs: optional tenant, destination, property.
Output: resolved account context, defaults, capabilities, and limitations.

`get_destination_intelligence`

Primary tool for destination, market, apartment/STR, demand, event, holiday, pickup, occupancy, compression, pricing, and broad revenue-manager questions.

Inputs: optional tenant, destination, property, date preset or custom range, property type, question.
Output: intent, exact/inferred/unavailable answer mode, executive answer, evidence, affected dates, sources used, KPI coverage, recommended actions, and caveats.

`get_market_briefing`

Backward-compatible briefing that uses the same destination intelligence aggregation for broad market questions.

Inputs: optional tenant, destination, property, date preset or custom range.
Output: summary, evidence items, recommended actions, coverage, caveats.

`get_pricing_opportunities`

Returns date-level revenue-management actions for the authenticated property.

Inputs: optional tenant, destination, property, date preset or custom range, strategy.
Output: increase/hold/decrease/watch actions with reasons, signals, risks, and next steps.

`get_competitor_insights`

Combines current competitor rates with recent competitor rate movers.

Inputs: optional tenant, destination, stay window, observation window, LOS, adults, currency, competitors.
Output: biggest movers, current rate range, recommended watch actions, coverage, caveats.

`get_demand_drivers`

Explains demand by combining destination demand scores with events and holidays.

Inputs: optional tenant, destination, date preset or custom range.
Output: per-date demand level, drivers, explanation, confidence, and data completeness.

`search_competitor_rates`

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

Inputs: optional 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_destination_events`

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

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

`explain_rate_opportunity`

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

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

Examples

Call Titan tools

Start with get_revenue_manager_context for natural revenue-manager questions. Low-level discovery tools remain available for drilldown. Explicit tenant_id remains supported but is optional.

Revenue manager context

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": "get_revenue_manager_context",
      "arguments": {}
    }
  }'

Destination intelligence

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": "get_destination_intelligence",
      "arguments": {
        "date_range_preset": "next_week",
        "question": "What should I watch in my destination next week?"
      }
    }
  }'

Pricing opportunities

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": 6,
    "method": "tools/call",
    "params": {
      "name": "get_pricing_opportunities",
      "arguments": {
        "date_range_preset": "next_30_days",
        "strategy": "balanced"
      }
    }
  }'

Competitor insights

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": 7,
    "method": "tools/call",
    "params": {
      "name": "get_competitor_insights",
      "arguments": {
        "observed_date_range_preset": "previous_7_days",
        "stay_date_range_preset": "next_30_days",
        "length_of_stay": 1,
        "adults": 2,
        "currency": "EUR"
      }
    }
  }'

Apartment 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": 8,
    "method": "tools/call",
    "params": {
      "name": "get_destination_intelligence",
      "arguments": {
        "start_date": "2026-06-08",
        "end_date": "2026-06-14",
        "property_type": "apartments",
        "question": "Is there demand next week on apartments?"
      }
    }
  }'

Property-type demand breakdown

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": 9,
    "method": "tools/call",
    "params": {
      "name": "get_destination_intelligence",
      "arguments": {
        "start_date": "2026-06-08",
        "end_date": "2026-06-14",
        "question": "Can you break down demand by property type?"
      }
    }
  }'

Demand drivers

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": 10,
    "method": "tools/call",
    "params": {
      "name": "get_demand_drivers",
      "arguments": {
        "date_range_preset": "next_14_days"
      }
    }
  }'

Security and limits

Safe integration rules

Tenant isolation

The API key account is the default tenant. Explicit tenant_id values must match it. 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.

Agent routing

Call get_revenue_manager_context once, reuse the default destination/property context, and route destination, market, apartment, STR, competitor, event, holiday, pickup, weak-date, high-demand, and pricing questions to get_destination_intelligence. Do not report missing STR data until this tool has checked fallback Titan signals.

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.	Call `whoami`, then 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.