MCP Response UX Guide

Canonical reference for how every MCP tool response is structured, formatted, and rendered to the AI client (Cursor, CLI agent, or control-center UI).

Response Structure

{
  "_context": {
    "scope": "ecosystem",
    "ecosystem": "amof-platform",
    "breadcrumb": "global > amof-platform",
    "run_id": null,
    "session_id": "sess_abc123",
    "timestamp": "2026-03-02T14:30:00Z"
  },
  ...tool-specific fields...
}

Rendered Layout

[breadcrumb] Summary line (one sentence, past tense)

Key details (structured: table, bullets, or key-value pairs)

Next: [Action1](tool_name) [Action2](tool_name) [Action3](tool_name)

Summary line: max 80 characters, starts with outcome verb
Key details: 3-15 lines for normal cases
Total visible response: target 20 lines or fewer
Suggested actions: always 2-5, context-aware

Response Templates

Success Response

[amof-platform] Synced 3 repos successfully.

REPO            RESULT           DETAIL
amof            up to date       —
amof-ui         2 commits pulled feat/amof-cloud
amof-backend    up to date       —

Duration: 4.2s

Next: [Status](amof_get_ecosystem_status) [Push](amof_push_ecosystem)

Error Response

[amof-platform] Sync failed — amof-backend could not reach remote.

ERROR: fatal: Could not read from remote repository.
  Repo: amof-backend
  Exit code: 128

Partial result:
  ✓ amof: synced
  ✓ amof-ui: synced
  ✗ amof-backend: connection refused

Next: [Retry sync](amof_sync_ecosystem) [Check status](amof_get_ecosystem_status)

Confirmation Required

[amof-platform] Push requires confirmation.

This will push to remote:
  amof            feat/amof-cloud → origin
  amof-ui         feat/amof-cloud → origin  (2 commits ahead)
  amof-backend    feat/amof-cloud → origin

⚠ This sends code to remote and cannot be undone.

Confirm: [Yes, push](confirm) [Cancel](cancel)

Long-Running Action

[amof-platform] Install started — tracking as run:4e8c...

Run ID: 4e8c1d72-a3b4-4f89-9012-def456789abc
Action: install
Status: queued → running

This may take 30-120 seconds.

Next: [Stream logs](amof_get_run_logs) [Run status](amof_get_run_status)

Release Status

[release] Current version: v1.2.3-alpha.2 (pre-release)

  Tag:       v1.2.3-alpha.2
  Branch:    feat/amof-cloud
  Stage:     alpha (pre-release)
  Commits:   7 since v1.2.3-alpha.2

Next versions:
  v1.2.3-alpha.3    amof_release_bump(part="patch", pre="alpha")
  v1.2.3-beta.1     amof_release_promote(target="beta")
  v1.2.3            amof_release_promote(target="stable")

Next: [Bump alpha](amof_release_bump) [Promote to beta](amof_release_promote)

Formatting Rules

Tables

Column headers: UPPERCASE
Alignment: left-align text, right-align numbers
Max columns: 6
One blank line before and after table

Status Markers

Pass: check mark
Warning: warning triangle
Fail: cross mark
Neutral: bullet

Line Budget

Response Type	Target Lines	Max Lines
Success	8-12	20
Status/Info	10-15	20
Error	8-15	20
Confirmation	10-18	25
Long-running start	6-8	12
Blocked	6-10	15
Release status	15-20	30

Suggested Actions Format

Next: [Label](tool_name) [Label](tool_name)

Outcome	Primary Action	Secondary Actions
Success	Natural next step	Status check, related operations
Error	Retry or fix prerequisite	View logs, check status
Partial success	Fix failing part	View logs, retry
Long-running	Stream logs	Run status, list runs
Confirmation	Confirm or cancel	Safer alternative
Blocked	Unblock action	Alternative approach