Developer docs · v0.1

Dott MCP

The Model Context Protocol interface to your Dott portfolio. Connect Claude Desktop, claude.ai connectors, or any agent that speaks MCP — give it read-only access to events, scores, budgets, speakers, attendance, tier recommendations, and tasks.

Quickstart

1. Generate an API key from Settings → API Keys. The raw key appears once — copy it then. Org-management capability is required to generate or revoke keys.

2. Add the MCP server to your Claude Desktop config (typically ~/Library/Application Support/Claude/claude_desktop_config.json on macOS). We use mcp-remoteas the stdio↔HTTP bridge (Anthropic's recommended adapter for any HTTP-based MCP server):

{
  "mcpServers": {
    "dott": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://usedott.com/api/mcp",
        "--header",
        "x-dott-api-key:${DOTT_API_KEY}"
      ],
      "env": {
        "DOTT_API_KEY": "dott_sk_..."
      }
    }
  }
}

3. Restart Claude Desktop. Test the connection with any of the 8 tools below. From the command line:

curl -X POST https://usedott.com/api/mcp \
  -H "x-dott-api-key: dott_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Authentication

Every request must include an x-dott-api-keyheader. Keys are org-scoped — a key generated in one workspace returns only that workspace's data. The hash is stored; the raw key is never recoverable after generation.

Keys can be revoked at any time from Settings → API Keys. Revocation is immediate.

Rate limits

Each key has a per-hour request quota (defaults to 100/hour; contact support for higher). When you hit the limit you'll get an HTTP 429 with a Retry-After header. Counts reset on a rolling hour window.

Handle the 429 by waiting the number of seconds in the Retry-After header before retrying. Example handling pattern:

if (response.status === 429) {
  const retryAfter = parseInt(response.headers.get('Retry-After') || '60', 10);
  await new Promise(r => setTimeout(r, retryAfter * 1000));
  // retry
}

The 8 tools

v0.1 exposes 8 read-only tools. All take an authenticated request and return JSON. All are scoped to the org tied to the API key — there is no cross-org access by design.

get_event

Read a single event's identity, dates, format, tier, stage, scope, sub-type, intent category, registered/checked-in counts, planned and actual investment, the Dott Score, and the post-event verdict.

Input

event_id (UUID)

Returns

Event object with safe fields only — no scoring internals, no retro narrative, no PII.

get_portfolio

Get portfolio analytics — event count, total investment, average score, stage distribution, and the top events for the year.

Input

year (optional integer — defaults to current year)

Returns

Aggregated portfolio summary scoped to the calling org.

get_score

Get the Dott Score for an event — the composite 0–100 score that captures planning quality, delivery, and proof. Internals are proprietary; the final value and the category it was scored against are exposed.

Input

event_id (UUID)

Returns

{ score, intent_category } — no formula, no weights, no per-component breakdown.

get_budget

Read an event's budget summary — planned investment, actual spend, variance, and a breakdown by spend type.

Input

event_id (UUID)

Returns

Budget object scoped to the org.

get_speakers

Read the speaker roster for an event — names, titles, companies, sessions, confirmation status.

Input

event_id (UUID)

Returns

Array of speaker objects.

get_attendance

Read attendance stats for an event — registered count, checked-in count, show rate, no-shows, cancellations.

Input

event_id (UUID)

Returns

Attendance object scoped to the org.

get_tier_recommendation

Get Dott's portfolio-tier recommendation for an event — T0 · Flagship, T1 · Priority, T2 · Standard, T3 · Light, or T4 · Monitor — based on planning signals like budget, format, attendance, intent, and planning depth.

Input

event_id (UUID)

Returns

{ tier, confidence, reason } — or null if the event has fewer than two meaningful signals.

get_tasks

Read the tasks for an event — what's open, who owns it, when it's due. Useful for agents that need to know what's left before the event runs.

Input

event_id (UUID)

Returns

Array of { title, assignee, due_date, status, category, source, priority }. Org-scoped.

The Dott Score

The Dott Score is a composite 0–100 score that captures the full lifecycle of an event — what was planned, what was delivered, and what was proven. It folds three returns into one number: ROI (return on investment), ROO (return on objective), and ROX (return on experience).

get_score exposes the final score and the intent category the event was scored against. The internal weights, the per-component breakdowns, and the intent-specific weight tables are proprietary and not exposed via the MCP. Agents have everything they need to compare events, rank a portfolio, or explain a verdict — without the methodology that produced the verdict.

Audit log

Every authenticated MCP call writes a row to mcp_audit_log — api_key_id, org_id, response status, timestamp. Org operators with manage capability can review it via Supabase (a UI view ships in a later release). The log exists for incident response and abuse detection; it never contains the request payload or response body.

What MCP does not expose

v0.1 is read-only and intentionally scoped. The MCP layer never returns:

Scoring formula, weight tables, or intent-specific weight distributions
Per-component score breakdowns (pre-event signals, post-event evidence components)
Forecast targets, registration targets, show-rate targets, or the score-history time series
Retro narrative content, internal team notes, or learning capture
PII fields (submitter email, submitted-by user IDs)
Agent runtime state or conversation history

These boundaries are enforced in lib/mcp/blocked-fields.ts as a canonical sentinel list, separate from each tool's safe-field selection.

Errors

The MCP returns generic error messages — {"error": "..."} with an appropriate HTTP status. Server-side details aren't echoed back to clients (security posture).

401 — missing or invalid x-dott-api-key
429 — rate limit exceeded; check Retry-After
500 — internal error; we'll see it in audit + logs

Support

MCP issues, integration help, security disclosures: email hello@usedott.com. Meet the team behind Dott at /team.

Use & legal

Use of the Dott MCP is governed by our Terms and Privacy Policy. Keys are scoped to a single org — sharing one across orgs, reselling access, or wrapping the MCP into a competing product is not permitted. Rate limits, audit logs, and revocation are operator-facing controls; abuse triggers automatic key suspension while we follow up.

Dott, the Dott Score, and the Event Portfolio Intelligence System are proprietary — no copying, scraping, reverse-engineering, or reproduction without written permission. The MCP exposes a deliberately scoped read-only surface; everything outside that surface is part of the proprietary methodology and isn't available for export.

v0.1 — May 27, 2026. The MCP surface is versioned; we'll publish a changelog before adding new tools or changing existing shapes.