Dott
Developer docs · v0.2

Dott MCP

The Model Context Protocol interface to Dott. Connect Claude Desktop, claude.ai connectors, or any agent that speaks MCP. This page covers two servers: the public, accountless knowledge + discovery MCP (Dott's published concepts, the open scoring methodology, and the event directory), just below, and the authenticated portfolio MCP that follows it (read-only access to your own events, scores, budgets, speakers, attendance, tier recommendations, and tasks).

Public MCP: knowledge + discovery (accountless)

Dott runs a public, read-only MCP (no account, no API key) covering two layers: knowledge (the concepts Dott defines and the published scoring methodology, always available) and discovery (the public event directory). It's a separate surface from the operator MCP below: server dott-public, endpoint https://www.usedott.com/api/mcp/public (remote, streamable HTTP). Everything this page says about keys, rate-limit headers, org scoping, and the audit log applies to the operator server only.

Knowledge tools

discover_concepts
Browse the Dott Intelligence library: every concept Dott defines and publishes (the Dott Score, intent-weighted scoring, forecast accuracy, …), each with its public definition, lifecycle phase, and pillar page. Same definitions as /api/ontology and the pillar pages, from one source.
Input
None
Returns
All defined concepts plus pointers to the human-readable library (/intelligence) and the JSON-LD ontology (/api/ontology).
get_concept
One concept's full public definition by its slug (shown in discover_concepts), plus its canonical page URL when the pillar is live.
Input
slug (from discover_concepts, e.g. dott-score)
Returns
The concept, or an honest not-found listing every valid slug.
get_scoring_methodology
The published Dott Score methodology as structured data: the Combined formula and weights, the eight Pre-Event signals with points, the full intent-weight matrix, the score bands with exact cutoffs, and the withhold-gate rule. Single-sourced from the same engine constants that score every event.
Input
None
Returns
The method, versioned: what /dott-score-methodology publishes, as JSON. Tier-safe: no benchmark data, no per-event internals.

Discovery tools

discover_events
Search the public event directory: topic, region, date_from/date_to, event_type, pricing, source (dott_measured | curated_external), min_score, multi_day, limit. Default order is Most Proven: published outcomes first.
Input
All filters optional
Returns
Listed events, public columns only. Measured events carry Dott's proof (expected attendance → what actually showed → a 0–100 Dott Score) only when the operator has published the outcome.
get_event
One event's full public listing by its /e/<slug> address, including the outcome proof when the operator has published it. Curated external listings aren't individually addressable. Follow their register link from discover_events.
Input
slug (from the event's /e/<slug> URL)
Returns
Public listing fields only: no scoring internals, no PII, no base tables.

Connect (Claude Desktop)

{
  "mcpServers": {
    "dott-public": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://www.usedott.com/api/mcp/public"]
    }
  }
}

On claude.ai, add https://www.usedott.com/api/mcp/public as a custom connector, auth None. Quick test from the command line, no key:

curl -X POST https://www.usedott.com/api/mcp/public \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Running Dott locally or on a preview deploy without DOTT_DIRECTORY_PUBLIC? The two discovery tools answer with a not-open-yet notice and no event data until that flag is set. The knowledge tools always answer: that content is public everywhere.

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-remote as the stdio↔HTTP bridge (Anthropic's recommended adapter for any HTTP-based MCP server):

{
  "mcpServers": {
    "dott": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://www.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://www.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-key header. 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. The method itself is published (see the public server's get_scoring_methodology); this tool returns the final value and the category it was scored against.
Input
event_id (UUID)
Returns
{ score, intent_category }. No per-event component breakdown (that stays in the operator's workspace).
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 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.2: August 13, 2026 (public server dott-public 0.2.0: knowledge tools added; authed server unchanged at 0.1). The MCP surface is versioned; we'll publish a changelog before changing existing shapes.