Dock Optimizer MCP

📖 Overview

The MCP surface is a single JSON-RPC 2.0 endpoint that AI agents (Zo, Claude Desktop, LangChain, Cursor) use to read state and propose actions. It exposes:

• ~12 tools for writes — split into auto-confirm (execute immediately) and human-in-the-loop (queue for admin approval)
• 25 tenant + 9 platform resources for reads — appointments, doors, inventory, assets, operations dashboards
• Live discovery via tools/list and resources/list, plus a static manifest at /api/mcp/manifest.json

For partner TMS/ERP polling without JSON-RPC, see the REST surface instead. Both share one credential, one rate-limit bucket, one audit trail.

🔐 Authentication

All API requests require a Bearer token in the Authorization header. API keys are organization-specific — an admin in your organization generates them from the Integration Hub → Agent Keys tab. Each key is scoped to that organization's data.

curl -X POST https://dockoptimizer.com/api/mcp/v1/message \
  -H "Authorization: Bearer do_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Key Scopes

Scopes gate the write-capable RPC methods. Discovery (tools/list and resources/list) is always allowed so a client can introspect the server regardless of what it's permitted to do.

Capability Gating (Fine-Grained Access)

Scopes gate methods; capabilities gate individual tools. Sensitive tool families check the key's agentConfig.capabilities[] array and return SCOPE_DENIED if the capability is missing. Use this to keep a booking agent from touching stock, or an inventory agent from moving appointments.

Configure per key via POST /api/agent-keys/{id}/update-metadata with an agentConfig payload:

{
  "version": 1,
  "capabilities": ["appointments", "inventory"],
  "defaultFacilityId": 19,
  "notes": "Zo booking agent, prod"
}

Environment Tagging

Keys may carry an environment tag of staging or production. The auth filter compares that tag against the server's ASPNETCORE_ENVIRONMENT on every request — a tagged key whose environment doesn't match the server is rejected with 401. Tenant keys may leave the tag blank for legacy compatibility.

Key Identity & Metadata

Every key carries identifying metadata so admins can distinguish one agent from another on the dashboard and in audit logs:

Rotation & Revocation

• Rotate regularly — Call POST /api/agent-keys/{id}/regenerate to atomically revoke the old token and issue a new one with the same metadata. Recommended cadence: 90 days for production agents, 30 days for shared developer keys.
• Revoke immediately if a token is ever logged, committed, or leaves the owner's machine. POST /api/agent-keys/{id}/revoke takes effect on the next request.
• Never embed keys in client-side code — browsers, mobile apps, and public repos are not safe hosts. Agents must call the API from a server or trusted workstation.

📡 Endpoint

The MCP surface uses JSON-RPC 2.0 over a single HTTP endpoint. All requests are POST with a JSON body.

Request Format

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

Handshake

Strict MCP clients (Claude Desktop, MCP Inspector) must send initialize first and won't proceed until the server replies with protocolVersion, capabilities, and serverInfo. DockOptimizer answers this call and acknowledges notifications/initialized with an empty result.

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": { "protocolVersion": "2025-06-18" },
  "id": 1
}

Only wired-up capabilities are advertised — resources/subscribe, sampling/*, logging/*, and prompts/* are deliberately omitted so compliant clients don't call them.

Idempotency

Tools that aren't naturally idempotent (propose_appointment) accept an Idempotency-Key HTTP header. A retry with the same key within 24h replays the original response (no duplicate booking). Reuse with different arguments returns JSON-RPC error -32002 so the client fails loudly instead of silently submitting a changed payload.

Available Methods

🔧 Tools

Tools represent write operations that modify system state. Tools are split into two categories:

• auto-confirm Execute immediately and return the result — no human approval needed
• HITL Queued for Human-in-the-Loop approval — admins are notified in real-time via push notification

Auto-Confirmed Tools

These tools execute immediately and return the result inline.

Inventory Tools

Require the inventory capability on the key (combine with write, e.g. read,write,inventory). Every transaction is audited with agent attribution and broadcasts a SignalR toast to users in the org.

File Upload

File uploads use a dedicated multipart endpoint rather than tools/call. The call is audited under method upload_file.

Human-in-the-Loop (HITL) Tools

These tools queue the action for admin approval. Admins receive a real-time push notification and can approve or reject from the dashboard.

Example: Call a Tool

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "propose_appointment",
    "arguments": {
      "facilityId": 19,
      "scheduledDate": "2026-03-18",
      "scheduledTime": "14:00",
      "carrierName": "FedEx Freight",
      "bolNumber": "BOL-2026-0318",
      "notes": "Palletized shipment, 2 skids"
    }
  },
  "id": 2
}

Response (Auto-Confirmed)

{
  "jsonrpc": "2.0",
  "result": {
    "content": [{
      "type": "text",
      "text": "Appointment created and confirmed.\n{\"eventId\":1234,\"facilityId\":19,\"scheduledDate\":\"2026-03-18\",\"scheduledTime\":\"14:00\"}"
    }]
  },
  "id": 2
}

Response (HITL Queued)

{
  "jsonrpc": "2.0",
  "result": {
    "content": [{
      "type": "text",
      "text": "Action 'propose_block_door' successfully queued for Human-in-the-Loop review. Action ID: 42."
    }]
  },
  "id": 2
}

📊 Resources

Resources represent read-only data about your facility's current state. Use resources/list to discover all available URIs at runtime.

Appointments

Doors & Facilities

Organization & Operations

Carriers & Inventory

Example: Read a Resource

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

🧭 Discovery Manifest

MCP-compatible clients (Zo, Claude Desktop, LangChain, Cursor) can auto-discover the server's capabilities via a public manifest. Use it to bootstrap your agent's tool/resource registry without hardcoding URIs.

❌ Error Handling

The API uses standard JSON-RPC 2.0 error codes alongside HTTP status codes. Error responses include an optional data.hint field with recovery guidance for agents.

RFC 7807 Problem Details (REST + transport-level MCP errors)

Unhandled errors on /api/v1/* and transport-level errors on /api/mcp/* come back as application/problem+json:

{
  "type": "https://dockoptimizer.com/errors/internal",
  "title": "Internal server error",
  "status": 500,
  "detail": "An unexpected error occurred. Our team has been notified.",
  "instance": "/api/v1/appointments",
  "requestId": "8f4d2c1a7b6e4e3f9a0c1b8d2e7f4a9c"
}

JSON-RPC error codes (MCP)

Recovery Hints

Error responses may include a data.hint field with actionable guidance:

{
  "error": {
    "code": -32002,
    "message": "Resource not found or empty result for URI: dock://appointments/99999",
    "data": {
      "hint": "The requested resource returned no data. Check the appointment ID or filters."
    }
  }
}

⚡ Rate Limits

API requests are rate-limited per API key across three windows. The three layers protect against burst traffic, runaway loops, and accidental write storms from a single agent. REST and MCP traffic share the same bucket — the limits below are per key, not per surface.

429 Response Headers

When rate-limited, the API returns HTTP 429 Too Many Requests. The minute-window limiter is a token bucket — the bucket refills continuously. The daily window resets at 00:00 UTC.

Right-sizing Per-Key Limits

Use writeRateLimit on keys that should only make occasional changes (a data-quality agent, a report runner). Leave it null for keys that may legitimately run bursts (a bulk backfill import). The per-minute burst limit still applies either way.

🔑 Key Management

Manage API keys programmatically via the admin endpoints (requires an authenticated admin session cookie — these endpoints are not callable from an agent using its own API key). The same keys work for both REST and MCP traffic.

🛡️ Multi-Agent & RBAC Best Practices

Dock Optimizer is designed for organizations running multiple agents at once — Conmitto-operated agents (Zo Computer), third-party orchestrators, and customer-owned agents built by end users. Use the checklist below to keep the permission model honest as that fan-out grows.

One Key Per Agent, Per Environment

• Never share a single key across logically distinct agents. If the booking agent and the data-quality agent both run from zo, give each its own key so rate limits and audit logs are separable.
• Generate a distinct key in each environment — even for the same agent. A staging key accidentally pointed at production should fail because no production key exists with that secret, not because of an environment label.
• Name keys predictably: <tenant>-<agent>-<env> — e.g. kobelco-zo-booking-prod, akash-claude-desktop-dev.

Least-Privilege by Default

1. Start every new key with scopes: "read". Only add write when the agent demonstrably needs to mutate state.
2. Restrict the agentConfig.capabilities array to the specific tool families the agent uses (["appointments"], ["inventory"], or both).
3. For agents that only perform occasional writes (daily rollup, nightly flag cleanup), set an explicit writeRateLimit so a runaway loop is capped.

Customer (BYO) Agents

End users in an organization can generate their own API keys from Integration Hub → Agent Keys. Customer agents inherit the organization's data boundary automatically — they cannot read or modify any other tenant's data. What you do control as an admin:

• Approve or reject key generation via your Integration Hub permission policy.
• Require contactEmail and description on every key so you can page the owner when something misbehaves.
• Set short expiresAt values (30–90 days) on user-generated keys; rotations become a natural checkpoint.
• Review the dashboard weekly — stale keys with zero calls in 30 days should be revoked.

Platform (Zo / Conmitto-operated) Agents

Agents that Conmitto operates on behalf of a tenant (Zo Computer, internal automations) should:

• Be issued by the tenant's admin, not by the platform team — the tenant always owns the key.
• Be tagged with environment = staging or production for visibility.
• Carry a distinctive agentName prefix (e.g. zo-…) so audit logs make first-party traffic easy to spot.
• Use HITL tools (propose_*) for anything a human would want to review — door blocks, flagged appointments, ad-hoc report runs. Reserve auto-confirm tools for well-bounded user intents.

Incident Response

📒 Audit & Observability

Every authenticated MCP and REST request is written to the AgentAuditLogs table with the fields below. Logs are always scoped by CompanyId, so your organization only ever sees its own traffic.

Query per-key activity via GET /api/agent-keys/activity/{id}. Aggregate dashboard data — including recent activity samples per key — is available at GET /api/agent-keys/dashboard.

🚀 Getting Started

Follow these steps to connect your first AI agent with least-privilege defaults:

1. Generate an API Key — Navigate to Integration Hub → Agent Keys. Use a descriptive agentName (e.g. zo-booking-prod), set contactEmail, start with scopes: "read", and set an expiresAt 90 days out. Copy the do_live_... token immediately — it is shown only once.
2. Discover the Server — Fetch GET /api/mcp/manifest.json (unauthenticated) to bootstrap your client, then call tools/list and resources/list for the authoritative schema filtered to your key's scopes and capabilities.
3. Read Facility Data — Call resources/read with dock://facilities to get your facility IDs, then dock://operations/today for today's dashboard.
4. Promote to Write — Once your agent reliably reads the right data, rotate the key with scopes: "read,write" and the minimum capabilities array it needs. Test auto-confirm tools (e.g. propose_appointment) before enabling HITL flows.
5. Monitor & Iterate — Watch /api/agent-keys/activity/{id} during rollout, and set up a weekly review of /api/agent-keys/dashboard to catch stale or over-privileged keys.