docs/reference/mcp.md · gabriel/musehub

# MuseHub MCP Reference

> Protocol version: **2025-11-25** | Implementation: pure-Python async, no external MCP SDK

MuseHub treats AI agents as first-class citizens. The MCP integration gives agents complete capability parity with the web UI: they can browse, search, compose, review, and publish — over a standard protocol that every major agent runtime supports.

6

7

MCP 2025-11-25 adds the full **Streamable HTTP transport** (`GET /mcp` SSE push channel, session management, Origin security) and **Elicitation** (server-initiated user input via form and URL modes), enabling real-time interactive tool calls that interview users mid-execution.

---

## Table of Contents

1. [Architecture](#architecture)

14

2. [Transports](#transports)

15

3. [Authentication](#authentication)

16

4. [Session Management](#session-management)

17

5. [Elicitation](#elicitation)

18

6. [Tools — 40 total](#tools)

19

- [Read Tools (20)](#read-tools-20)

20

- [Write Tools (15)](#write-tools-15)

21

- [Elicitation-Powered Tools (5)](#elicitation-powered-tools-5)

22

7. [Resources — 29 total](#resources)

23

- [Static Resources (12)](#static-resources-12)

24

- [Templated Resources (17)](#templated-resources-17)

25

8. [Prompts — 10 total](#prompts)

26

9. [Error Handling](#error-handling)

27

10. [Usage Patterns](#usage-patterns)

28

11. [Architecture Diagrams](#architecture-diagrams)

---

## Architecture

```

MCP Client (Cursor, Claude Desktop, any SDK)

36

│

37

├─ HTTP POST /mcp (all client→server)

38

├─ HTTP GET /mcp (SSE push, server→client)

39

├─ HTTP DELETE /mcp (session termination)

40

└─ stdio python -m musehub.mcp.stdio_server (local dev)

41

│

42

musehub/api/routes/mcp.py ← Streamable HTTP transport (2025-11-25)

43

│

44

musehub/mcp/dispatcher.py ← async JSON-RPC 2.0 engine

45

│

46

┌───────┼───────────────┬────────────────┐

47

│ │ │ │

48

tools/call resources/read prompts/get notifications/*

49

│ │ │ │

50

Read executors Resource handlers Prompt Session/Elicitation

51

(musehub_mcp_executor.py) (resources.py) assembler (session.py)

52

Write executors (context.py)

53

Elicitation tools

54

(mcp/write_tools/elicitation_tools.py)

55

│

56

AsyncSession → Postgres

57

```

58

59

The dispatcher speaks JSON-RPC 2.0 directly. The HTTP envelope is always `200 OK` — tool errors are signalled via `isError: true` on the content block, not via HTTP status codes. Notifications (no `id` field) return `202 Accepted` with an empty body. Elicitation-powered tools return `text/event-stream` so the server can push `elicitation/create` events mid-call.

---

## Transports

### HTTP Streamable — Full 2025-11-25 Transport

#### `POST /mcp`

The production transport. Accepts `application/json`. Returns `application/json` for most requests, or `text/event-stream` for elicitation-powered tool calls.

```http

POST /mcp HTTP/1.1

Content-Type: application/json

74

Authorization: Bearer <jwt>

75

Mcp-Session-Id: <session-id> ← required after initialize

76

MCP-Protocol-Version: 2025-11-25 ← optional; validated if present

77

78

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

79

```

80

81

**Batch requests** — send a JSON array; responses are returned as an array in the same order (notifications are filtered out):

```http

POST /mcp

[

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

87

{"jsonrpc":"2.0","id":2,"method":"resources/list"}

]

```

**Notifications** (no `id`) return `202 Accepted` with an empty body.

92

93

#### `GET /mcp` — SSE Push Channel

94

95

Persistent server-to-client event stream. Required for receiving elicitation requests and progress notifications outside of an active tool call.

```http

GET /mcp HTTP/1.1

Accept: text/event-stream

100

Mcp-Session-Id: <session-id>

101

Last-Event-ID: <last-seen-event-id> ← optional; triggers replay

102

```

103

104

Returns `text/event-stream`. Server pushes:

105

- `notifications/progress` — tool progress updates

106

- `elicitation/create` — server-initiated user input requests

107

- `notifications/elicitation/complete` — URL-mode OAuth completion signals

108

- `: heartbeat` — comment every 15 s to keep proxies alive

109

110

#### `DELETE /mcp` — Session Termination

```http

DELETE /mcp HTTP/1.1

Mcp-Session-Id: <session-id>

115

```

116

117

Returns `200 OK`. Closes all open SSE streams and cancels pending elicitation Futures for the session.

118

119

### stdio — `python -m musehub.mcp.stdio_server`

120

121

The local dev and Cursor IDE transport. Reads newline-delimited JSON from `stdin`, writes JSON-RPC responses to `stdout`, logs to `stderr`.

122

123

**Cursor IDE integration** — create or update `.cursor/mcp.json` in your workspace:

```json

{

"mcpServers": {

"musehub": {

"command": "python",

"args": ["-m", "musehub.mcp.stdio_server"],

131

"cwd": "/path/to/musehub"

}

}

}

```

The stdio server runs without auth (trusted local process). Write tools are available unconditionally.

---

## Authentication

| Context | How |

|---------|-----|

| HTTP transport — read tools + public resources | No auth required |

146

| HTTP transport — write / elicitation tools | `Authorization: Bearer <jwt>` |

147

| HTTP transport — private repo resources | `Authorization: Bearer <jwt>` |

148

| stdio transport | No auth (trusted process) |

149

150

The JWT is the same token issued by the MuseHub auth endpoints (`POST /api/v1/auth/token`). The `sub` claim is used as the acting `user_id` for all write operations.

151

152

Attempting a write tool without a valid token returns a JSON-RPC error (`code: -32001`, `message: "Authentication required for write tools"`).

---

## Session Management

157

158

Session management is required for elicitation and the GET /mcp SSE push channel.

159

160

**Creating a session:**

```http

POST /mcp

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{"elicitation":{"form":{},"url":{}}}}}

```

Response includes:

```http

Mcp-Session-Id: <cryptographically-secure-session-id>

170

```

171

172

**Using the session:** include `Mcp-Session-Id` in all subsequent requests. Sessions expire after 1 hour of inactivity.

173

174

**Ending a session:** `DELETE /mcp` with the `Mcp-Session-Id` header.

175

176

**Security:** All requests are validated against an Origin allowlist (`localhost` always permitted; production: `musehub.app`). Requests from unlisted Origins are rejected with `403 Forbidden`.

---

## Elicitation

Elicitation is a MCP 2025-11-25 feature that allows the server to request structured input from the user *mid-tool-call*. MuseHub supports both modes:

### Form Mode

The server sends an `elicitation/create` request with a restricted JSON Schema object describing the fields to collect. The client shows a form to the user, then sends the response back via `POST /mcp`.

```

Agent MuseHub MCP

│ │

│ POST tools/call │

│ (musehub_create_with_preferences)

193

│──────────────────────────►│

194

│ │ opens SSE stream

195

│◄──────────────────────────│

196

│ SSE: elicitation/create │

197

│ {mode:"form", schema:{ │

198

│ key, tempo, mood, ...}}│

199

│◄──────────────────────────│

200

│ [user fills form] │

201

│ POST elicitation result │

202

│ {action:"accept", │

203

│ content:{key:"Dm",...}} │

204

│──────────────────────────►│

205

│ │ tool continues

206

│ SSE: tools/call response │

207

│◄──────────────────────────│

```

### URL Mode

The server sends an `elicitation/create` request with `mode:"url"` directing the user to a MuseHub OAuth page. After the user completes the flow, the callback fires `notifications/elicitation/complete` into the agent's SSE stream.

213

214

```

215

Agent MuseHub MCP Browser

216

│ │ │

217

│ POST musehub_connect_ │ │

218

│ streaming_platform │ │

219

│──────────────────────────►│ │

220

│ SSE: elicitation/create │ │

221

│ {mode:"url", url:"https://musehub.app/mcp/connect/spotify?..."}

222

│◄──────────────────────────│ │

223

│ [client opens URL] │──────────────────────►│

224

│ │ User authorises OAuth│

225

│ │◄──────────────────────│

226

│ SSE: notifications/ │ │

227

│ elicitation/complete │ │

228

│◄──────────────────────────│ │

229

│ SSE: tools/call response │ │

230

│◄──────────────────────────│ │

231

```

232

233

### Elicitation Schemas

234

235

MuseHub provides five musical form schemas:

236

237

| Schema key | Fields |

238

|------------|--------|

239

| `compose_preferences` | `key` (24 options), `tempo_bpm`, `time_signature`, `mood` (10 options), `genre` (10 options), `reference_artist`, `duration_bars`, `include_modulation` |

240

| `repo_creation` | `daw` (10 options), `primary_genre`, `key_signature`, `tempo_bpm`, `is_collab`, `collaborator_handles`, `initial_readme` |

241

| `pr_review_focus` | `dimension_focus` (all/melodic/harmonic/rhythmic/structural/dynamic), `review_depth` (quick/standard/thorough), `check_harmonic_tension`, `check_rhythmic_consistency`, `reviewer_note` |

242

| `release_metadata` | `tag`, `title`, `release_notes`, `is_prerelease`, `highlight` |

243

| `platform_connect_confirm` | `platform` (8 streaming services), `confirm` |

---

## Tools

All 40 tools use `server_side: true`. The JSON-RPC envelope is always a success response — errors are represented inside the content block via `isError: true`.

250

251

### Repo identification: `repo_id` or `owner` + `slug`

252

253

All repo-scoped tools accept either form. The dispatcher resolves `owner` + `slug` to a `repo_id` transparently — agents can use human-readable names without a prior lookup step:

254

255

```json

256

{ "repo_id": "abc-123-uuid" }

257

// or equivalently:

258

{ "owner": "cgcardona", "slug": "jazz-standards" }

```

### Calling a tool

```json

{

"jsonrpc": "2.0",

"id": 1,

"method": "tools/call",

268

"params": {

269

"name": "musehub_get_context",

270

"arguments": { "owner": "cgcardona", "slug": "jazz-standards" }

}

}

```

Response:

```json

{

"jsonrpc": "2.0",

"id": 1,

"result": {

"content": [{ "type": "text", "text": "{\"name\":\"my-song\", ...}" }],

"isError": false

}

}

```

---

### Read Tools (20)

#### `musehub_get_context`

293

294

**Start here.** Full AI context document for a repo — domain plugin (scoped_id, dimensions, capabilities), branches, recent commits, and artifact inventory in a single call. Always call this before creating or modifying state. For computed analytics, follow up with `musehub_get_domain_insights`. For the full viewer payload, follow up with `musehub_get_view`.

295

296

297

|-----------|------|----------|-------------|

---

#### `musehub_list_branches`

305

306

All branches with their head commit IDs and timestamps.

307

308

309

|-----------|------|----------|-------------|

---

#### `musehub_list_commits`

317

318

Paginated commit history, newest first.

319

320

321

|-----------|------|----------|-------------|

---

#### `musehub_read_file`

331

332

Metadata for a single artifact (MIDI, MP3, WebP, etc.) at a given commit.

333

334

335

|-----------|------|----------|-------------|

---

#### `musehub_search`

345

346

Keyword/path search over commits and file paths within a repo.

347

348

349

|-----------|------|----------|-------------|

---

#### `musehub_get_commit`

359

360

Single commit detail with the full snapshot manifest (all file paths and content hashes at that point in history).

361

362

363

|-----------|------|----------|-------------|

---

#### `musehub_compare`

372

373

Musical diff between two refs — returns per-dimension change scores (harmony, rhythm, groove, key, tempo) and a list of changed file paths.

374

375

376

|-----------|------|----------|-------------|

---

#### `musehub_list_issues`

386

387

Issues with optional state, label, and assignee filters.

388

389

390

|-----------|------|----------|-------------|

---

#### `musehub_get_issue`

401

402

Single issue with its full comment thread.

403

404

405

|-----------|------|----------|-------------|

---

#### `musehub_list_prs`

414

415

Pull requests with optional state and base branch filters.

416

417

418

|-----------|------|----------|-------------|

---

#### `musehub_get_pr`

428

429

Single PR with all inline comments and reviews.

430

431

432

|-----------|------|----------|-------------|

---

#### `musehub_list_releases`

441

442

All releases for a repo with asset counts and timestamps.

443

444

445

|-----------|------|----------|-------------|

---

#### `musehub_search_repos`

453

454

Discover public repos by text query or musical attributes.

455

456

457

|-----------|------|----------|-------------|

458

459

| `key` | string | no | Musical key filter (e.g. `"C major"`) |

---

#### `musehub_list_domains`

468

469

List all available domain plugins registered in MuseHub (e.g. MIDI, Genomics, Code).

470

471

_No parameters required._

---

#### `musehub_get_domain`

476

477

Full definition for a single domain plugin — scoped_id, version, dimension manifest, capabilities, and schema.

478

479

480

|-----------|------|----------|-------------|

---

#### `musehub_get_domain_insights`

486

487

Computed analytics for a repo using its domain plugin — per-dimension scores, distribution stats, and trend data.

488

489

490

|-----------|------|----------|-------------|

| `ref` | string | no | Branch, tag, or commit SHA (defaults to HEAD) |

---

#### `musehub_get_view`

499

500

Full viewer payload — dimension slices, navigation strip, and the current state for each registered dimension. Use after `musehub_get_context` for the visual-layer detail.

501

502

503

|-----------|------|----------|-------------|

| `ref` | string | no | Branch, tag, or commit SHA (defaults to HEAD) |

---

#### `musehub_whoami`

512

513

Return the authenticated user's profile. Useful for confirming token identity before write operations.

514

515

_No parameters required._

---

#### `muse_pull`

Pull latest commits from MuseHub into a local Muse working tree — equivalent of `muse pull` on the command line.

522

523

524

|-----------|------|----------|-------------|

---

#### `muse_remote`

Inspect remote tracking configuration and get the clone URL for a repo — equivalent of `muse remote` on the command line. Returns `clone_url`, `clone_command`, and `visibility`. Pass `ref` to pin to a specific branch or tag.

535

536

537

|-----------|------|----------|-------------|

| `ref` | string | no | Branch or tag to reference in the clone command |

542

543

---