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 — 32 total](#tools)

19

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

20

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

21

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

22

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

23

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

24

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

25

8. [Prompts — 8 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_compose_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 32 tools use `server_side: true`. The JSON-RPC envelope is always a success response — errors are represented inside the content block via `isError: true`.

### Calling a tool

```json

{

"jsonrpc": "2.0",

"id": 1,

"method": "tools/call",

258

"params": {

259

"name": "musehub_browse_repo",

260

"arguments": { "repo_id": "abc123" }

}

}

```

Response:

```json

{

"jsonrpc": "2.0",

"id": 1,

"result": {

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

"isError": false

}

}

```

---

### Read Tools (15)

#### `musehub_browse_repo`

283

284

Orientation snapshot for a repo: metadata, default branch, recent commits, top-level file list.

285

286

287

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

---

#### `musehub_list_branches`

293

294

All branches with their head commit IDs and timestamps.

295

296

297

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

---

#### `musehub_list_commits`

303

304

Paginated commit history, newest first.

305

306

307

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

---

#### `musehub_read_file`

315

316

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

317

318

319

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

---

#### `musehub_get_analysis`

327

328

13-dimension musical analysis for a repo at a given ref.

329

330

331

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

332

333

| `ref` | string | no | Branch, tag, or commit SHA |

---

#### `musehub_search`

339

340

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

341

342

343

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

---

#### `musehub_get_context`

350

351

Full AI context document for a repo — combines metadata, analysis, recent activity, and usage hints into a single structured payload.

352

353

354

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

---

#### `musehub_get_commit`

360

361

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

362

363

364

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

---

#### `musehub_compare`

371

372

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

373

374

375

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

---

#### `musehub_list_issues`

383

384

Issues with optional state, label, and assignee filters.

385

386

387

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

---

#### `musehub_get_issue`

396

397

Single issue with its full comment thread.

398

399

400

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

---

#### `musehub_list_prs`

407

408

Pull requests with optional state and base branch filters.

409

410

411

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

---

#### `musehub_get_pr`

419

420

Single PR with all inline comments and reviews.

421

422

423

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

---

#### `musehub_list_releases`

430

431

All releases for a repo with asset counts and timestamps.

432

433

434

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

---

#### `musehub_search_repos`

440

441

Discover public repos by text query or musical attributes.

442

443

444

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

445

446

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

---

### Write Tools (12)

> All write tools require `Authorization: Bearer <jwt>` on the HTTP transport.

457

458

#### `musehub_create_repo`

459

460

Create a new repository.

461

462

463

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

---

#### `musehub_fork_repo`

477

478

Fork an existing repository into the authenticated user's account.

479

480

481

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

---

#### `musehub_create_issue`

Open a new issue.

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

---

#### `musehub_update_issue`

503

504

Update issue state or metadata.

505

506

507

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

---

#### `musehub_create_issue_comment`

519

520