Model Context Protocol

Overview

The Dock Optimizer MCP (Model Context Protocol) integration allows AI agents to securely interact with your environment. Through this single entry point, agents can discover available data (Resources) and execute actions (Tools) while maintaining strict multi-tenant isolation.

Authentication

All requests to the MCP API must be authenticated using an API Key generated from the Integration Hub.

Authorization: Bearer do_live_Y0uRAp1K3Yh3rE...

Key Features

• Keys are strongly hashed using SHA-256 before storage.
• Keys can be revoked instantaneously via the Admin Dashboard.
• Every key is strictly tied to a single Company context.
• Keys support scoped permissions: read, write, or read,write.
• Optional expiration dates for time-limited access.

Endpoints

Resources (Read-Only)

Resources provide read-only access to data. Use resources/read with a URI to fetch data.

Tools (Write Operations)

All tools go through Human-in-the-Loop approval. When called, the action is queued and an admin must approve it before execution.

Request / Response Examples

List Resources

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resources/list"
}

Read Appointments (Last 7 Days, Checked In)

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "resources/read",
  "params": {
    "uri": "dock://appointments?start=2026-03-01&end=2026-03-07&status=checked_in&limit=20"
  }
}

Read Single Appointment

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "resources/read",
  "params": {
    "uri": "dock://appointments/101"
  }
}

Flag Appointment (Tool Call)

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "propose_flag_appointment",
    "arguments": {
      "appointmentId": 101,
      "flagReason": "Check-in time recorded but no checkout — appointment ended 3 hours ago",
      "severity": "high"
    }
  }
}

Tool Call Response (Queued for Approval)

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Action 'propose_flag_appointment' successfully queued for Human-in-the-Loop review. Action ID: a1b2c3d4-... You must wait for an Admin to approve this before it takes effect."
      }
    ]
  }
}

Error Handling

Errors follow the JSON-RPC 2.0 error format with an additional data.hint field providing recovery guidance for agents.

{
  "jsonrpc": "2.0",
  "id": 5,
  "error": {
    "code": -32001,
    "message": "Unknown resource URI: 'dock://invalid'",
    "data": {
      "hint": "Check the resource URI format. Use resources/list to see available URIs."
    }
  }
}

Error Codes

Rate Limits

To ensure system stability, the MCP endpoint enforces strict rate limitations:

Requests exceeding this threshold will receive a 429 Too Many Requests response. Please implement exponential backoff in your agent retry logic.

Safety & Human-in-the-Loop (HITL)

Dock Optimizer employs a secure Human-in-the-Loop (HITL) architecture for all Agent tool calls that modify data.

When an agent invokes tools/call, the action is not executed immediately. Instead, it is routed to an isolated sandbox queue table. Facility administrators are alerted instantly via SignalR, and they must manually Review and Approve the payload before execution.