MCP tool reference - ai-cmo.dev

The server exposes 10 tools and no resources or prompts. Every tool except aicmo_whoami (which takes no parameters at all) accepts an optional workspace parameter (a ai-cmo.dev workspace slug). When omitted, the server resolves the workspace from the credential or picks the sole accessible workspace; if multiple workspaces are available the tool returns an error asking you to choose.

`aicmo_whoami`

Title: ai-cmo.dev identity and workspaces
Description: List the workspaces accessible to this ai-cmo.dev credential and its authorized default. Input parameters: None REST endpoint: GET /api/v1/workspaces
Scope: workspace:read Example result:

{
  "authorizedWorkspace": "acme",
  "workspaces": [
    {
      "id": "acme",
      "displayName": "Acme"
    },
    {
      "id": "acme-eu",
      "displayName": "Acme Europe"
    }
  ]
}

`aicmo_score`

Title: ai-cmo.dev score
Description: Get the explainable GEO score for a workspace. Input parameters: REST endpoint: GET /api/v1/workspaces/{workspace}/score[?date=]
Scope: metrics:read Example result:

{
  "workspace": "acme",
  "date": "2026-08-10",
  "value": 61.4,
  "delta": 2.7,
  "n": 480,
  "formulaVersion": "geo-score-v1",
  "components": [
    {
      "key": "visibility",
      "label": "Visibility",
      "description": "Share of answers that mention the brand.",
      "rawValue": 0.42,
      "score": 42.0,
      "weight": 0.25,
      "normalizedWeight": 0.25,
      "n": 480
    },
    {
      "key": "relative_sov",
      "label": "Relative share of voice",
      "description": "Brand mentions against competitor mentions.",
      "rawValue": 0.71,
      "score": 71.0,
      "weight": 0.35,
      "normalizedWeight": 0.35,
      "n": 480
    }
  ],
  "missingComponents": [
    "sentiment"
  ],
  "trend": [
    {
      "date": "2026-08-03",
      "value": 58.7,
      "n": 460
    },
    {
      "date": "2026-08-10",
      "value": 61.4,
      "n": 480
    }
  ],
  "volumeProxy": {
    "source": "engines.yaml grounded usage weights",
    "engineWeights": {
      "chatgpt": 0.3,
      "gemini": 0.2,
      "perplexity": 0.2,
      "claude": 0.2,
      "grok": 0.1
    }
  }
}

`aicmo_scoreboard`

Title: ai-cmo.dev scoreboard
Description: Get per-engine visibility metrics for a workspace. Input parameters: REST endpoint: GET /api/v1/workspaces/{workspace}/scoreboard
Scope: metrics:read Example result:

{
  "brand": "acme",
  "date": "2026-08-10",
  "composite": {
    "value": 0.42,
    "ciLow": 0.38,
    "ciHigh": 0.46,
    "n": 480,
    "entity": "acme",
    "deltas": {
      "previous": 0.03,
      "7d": 0.05,
      "28d": 0.11
    }
  },
  "engines": [
    {
      "engine": "chatgpt",
      "metrics": {
        "visibility": {
          "value": 0.48,
          "ciLow": 0.42,
          "ciHigh": 0.54,
          "n": 160,
          "entity": "acme",
          "deltas": {
            "previous": 0.02,
            "7d": 0.04,
            "28d": 0.09
          }
        }
      }
    }
  ]
}

`aicmo_recs_list`

Title: List ai-cmo.dev recommendations
Description: List recommendations grouped by lifecycle status. Input parameters: REST endpoint: GET /api/v1/workspaces/{workspace}/recs
Scope: recs:read Example result:

{
  "proposed": [
    {
      "rec_id": "rec_7f3a",
      "brand": "acme",
      "created_at": "2026-08-10T08:00:00.000Z",
      "type": "new_comparison_page",
      "topic": "pricing",
      "title": "Publish an Acme vs Competitor One comparison page",
      "rationale": "Competitor One is cited in 68% of comparison answers; Acme in 12%.",
      "brief": {},
      "evidence": {},
      "scores": {},
      "evidence_weeks": 4,
      "status": "proposed",
      "state_version": 1,
      "compliance_flag": false,
      "current_draft_id": null,
      "restore_target": null,
      "visibility_snapshot": null
    }
  ],
  "todo": [],
  "in_review": [],
  "done": [],
  "archived": []
}

`aicmo_rec_update`

Title: Update an ai-cmo.dev recommendation
Description: Apply a guarded recommendation lifecycle transition.

This is the only tool that mutates workspace records. (aicmo_ask also writes: it creates a thread and posts a message.) It uses optimistic-concurrency guards (expectedStatus + expectedVersion) to prevent conflicting updates.

Input parameters:

This MCP tool does not expose reviewEvidence, visibilitySnapshot, or draftId, even though the REST endpoint accepts them. Use the REST API directly if you need those fields.

REST endpoint: POST /api/v1/workspaces/{workspace}/recs/{id}/status
Scope: recs:write Example result:

{
  "stdout": "{\"rec_id\": \"rec_7f3a\", \"status\": \"todo\", \"version\": 4}\n",
  "stderr": ""
}

`aicmo_runs_list`

Title: List ai-cmo.dev runs
Description: List measurement runs for a workspace. Input parameters: REST endpoint: GET /api/v1/workspaces/{workspace}/runs
Scope: runs:read Example result:

[
  {
    "runId": "run_2026_08_10_acme",
    "brand": "acme",
    "date": "2026-08-10",
    "preset": "standard",
    "status": "succeeded",
    "engines": [
      "chatgpt",
      "claude",
      "gemini",
      "perplexity"
    ],
    "okCount": 476,
    "errorCount": 4,
    "skippedCount": 0,
    "totalCostUsd": 1.87,
    "budgetCapUsd": 5.0,
    "budgetCapped": false
  }
]

`aicmo_run_get`

Title: Get an ai-cmo.dev run
Description: Get one workspace run job by ID. Input parameters: REST endpoint: GET /api/v1/workspaces/{workspace}/runs/{id}
Scope: runs:read Example result:

{
  "id": "job_2f81c4",
  "brand": "acme",
  "kind": "run",
  "pid": 48213,
  "logPath": "data/logs/job_2f81c4.log",
  "startedAt": "2026-08-10T09:14:02.114Z",
  "finishedAt": null,
  "status": "running",
  "progress": {
    "completedCalls": 180,
    "totalCalls": 480,
    "percent": 37.5,
    "source": "calls"
  },
  "lastLines": [
    "engine=chatgpt prompt=42/120 ok",
    "engine=claude prompt=18/120 ok"
  ]
}

`aicmo_reports_list`

Title: List ai-cmo.dev reports
Description: List stable report identities for a workspace. Input parameters: REST endpoint: GET /api/v1/workspaces/{workspace}/reports
Scope: reports:read Example result:

[
  {
    "id": "rep_2026_08_10_acme",
    "date": "2026-08-10"
  },
  {
    "id": "rep_2026_08_03_acme",
    "date": "2026-08-03"
  }
]

`aicmo_report_get`

Title: Get an ai-cmo.dev report
Description: Get a report by stable report ID. Input parameters: REST endpoint: GET /api/v1/workspaces/{workspace}/reports/{reportId}
Scope: reports:read Example result:

{
  "identity": {
    "id": "rep_2026_08_10_acme",
    "date": "2026-08-10"
  },
  "report": {
    "brand": "acme",
    "date": "2026-08-10",
    "summary": "Visibility up 2.7 points week over week."
  },
  "scoreboard": {
    "header": {
      "brand": "acme",
      "date": "2026-08-10",
      "display_name": "Acme",
      "engines_covered": [
        "chatgpt",
        "claude"
      ],
      "skipped_engines": []
    },
    "scoreboard": {
      "brand": "acme",
      "date": "2026-08-10",
      "composite": {
        "value": 0.42,
        "ciLow": 0.38,
        "ciHigh": 0.46,
        "n": 480,
        "entity": "acme",
        "deltas": {
          "previous": 0.03,
          "7d": 0.05,
          "28d": 0.11
        }
      },
      "engines": []
    }
  },
  "markdown": "# Acme - 2026-08-10\n\nVisibility up 2.7 points week over week.\n",
  "competitorLinks": [
    {
      "name": "Competitor One",
      "url": "https://one.example"
    }
  ]
}

`aicmo_ask`

Title: Ask ai-cmo.dev
Description: Ask the workspace assistant and return its streamed response as one result. Input parameters: REST endpoint: POST /api/v1/chat (with thread creation via POST /api/v1/threads)
Scope: chat:write Unlike the other tools, the result is not a passthrough of a REST response: the server consumes the chat SSE stream and folds every text-delta into one string, returning its own aggregated envelope. Example result:

{
  "threadId": "thread_abc123",
  "text": "Based on your recent scores, the biggest opportunity is improving visibility for brand positioning queries. I recommend focusing on...",
  "events": []
}

​aicmo_whoami

​aicmo_score

​aicmo_scoreboard

​aicmo_recs_list

​aicmo_rec_update

​aicmo_runs_list

​aicmo_run_get

​aicmo_reports_list

​aicmo_report_get

​aicmo_ask

`aicmo_whoami`

`aicmo_score`

`aicmo_scoreboard`

`aicmo_recs_list`

`aicmo_rec_update`

`aicmo_runs_list`

`aicmo_run_get`

`aicmo_reports_list`

`aicmo_report_get`

`aicmo_ask`