Sync Licensing MCP Server

A local Model Context Protocol server that exposes the catalog and the business logic of a music sync-licensing platform: searching tracks by creative brief, checking their rights clearance, quoting a licence under conditional pricing rules, issuing the contract and registering the usage.

Built for CC3067 Redes (Universidad del Valle de Guatemala), Project 1. The MCP message flow is implemented directly on top of JSON-RPC 2.0 — no MCP SDK, no FastMCP, no framework. The server package depends on the Python standard library only.

Table of contents

1. The business case

2. Architecture

3. Requirements

4. Installation

5. Building the catalog

6. Usage

7. Tool reference

8. Pricing rules

9. Protocol details

10. Where the data comes from

11. Testing

12. Project layout

13. Project status

Related MCP server: MusicBrainz MCP Server

1. The business case

Sync licensing is the business model of platforms such as Epidemic Sound, Artlist and Musicbed: a creator or an ad agency must buy a licence before using a track in audiovisual content. The process has three frictions:

• Finding a track that fits the creative brief and the budget is slow.

• The legal status of a track is not obvious — it may contain samples that were never cleared, or be frozen by an authorship dispute.

• The price is not fixed. The same track costs one thing for an Instagram post and something else entirely for a national TV campaign.

This server turns that workflow into five tools an assistant can chain. It is not a search engine with a price list attached: the fee is computed from conditional rules, and the tools refuse operations that would put the client at legal risk.

2. Architecture

        ┌────────────────────────┐
        │  Host (chatbot / CLI)  │
        └───────────┬────────────┘
                    │  spawns as a subprocess
        ┌───────────▼────────────┐
        │   MCP client           │   client/mcp_cli.py
        └───────────┬────────────┘
                    │  JSON-RPC 2.0 over stdio
                    │  (one JSON object per line)
        ┌───────────▼────────────┐
        │   MCP server           │   synclicense_mcp/
        │                        │
        │   jsonrpc.py  framing  │
        │   server.py   dispatch │
        │   tools.py    5 tools  │
        │   pricing.py  rate card│
        │   contracts.py contracts
        │   catalog.py  catalog  │
        └───────────┬────────────┘
                    │
        ┌───────────▼────────────┐
        │  data/catalog.json     │  built by scripts/seed_catalog.py
        │  data/usage_log.jsonl  │  append-only audit log
        └────────────────────────┘

stdout carries protocol traffic only; every diagnostic the server prints goes to stderr, so piping the server's output never corrupts the stream.

3. Requirements

• Python 3.10 or newer (developed on 3.11).

• No other dependency to run the server.

• requests is only needed to pull real metadata from Jamendo, and pytest only to run the test suite. Both are in requirements.txt.

4. Installation

git clone https://github.com/ecarcamo/MCP-Local-Redes.git
cd MCP-Local-Redes

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

pip install -r requirements.txt

The package is not installed: it is imported from the repository root, so every command below is run from the project directory.

5. Building the catalog

The repository already ships a catalog at data/catalog.json with 800 real tracks pulled from the Jamendo API, so you can skip this section and go straight to Usage. Rebuild it only if you want a different size, a different seed, or a catalog that needs no credentials.

Offline mode (default, no credentials, no network)

python scripts/seed_catalog.py --offline --count 800

Deterministic: the same --seed always produces the same catalog. It also pins three known tracks at the top (TRK-00001 cleared, TRK-00002 with pending samples, TRK-00003 blocked), which makes the failure scenarios easy to demonstrate.

Jamendo mode (real Creative Commons metadata)

Register at https://devportal.jamendo.com to get a client_id, then:

cp .env.example .env
# edit .env and set JAMENDO_CLIENT_ID=your_client_id

python scripts/seed_catalog.py --jamendo --count 800

Track metadata comes from the API; the base fee and the rights status are still generated locally (see section 10). Popularity is taken from the API's own popularity_total ordering. The free Jamendo plan throttles bursts of requests and answers a throttled page with an empty result list rather than an error, so the script pauses between pages and retries an empty page before concluding the catalog is exhausted.

6. Usage

6.1 Run the guided demo

A scripted end-to-end run, useful as a smoke test. It spawns the server, plays the complete licensing conversation, and prints every JSON-RPC message that crosses the wire (--> sent, <-- received):

python client/mcp_cli.py --demo

The demo walks through: handshake → tools/list → search a track → check its clearance → quote it → issue the contract → register the usage → and three failure cases (a blocked track, a quote that belongs to another track, and an invalid argument).

Add --quiet to hide the raw protocol trace and see only the answers:

python client/mcp_cli.py --demo --quiet

6.2 Interactive session (the main way to use it)

A REPL to drive the server by hand, one tool at a time:

python client/mcp_cli.py --interactive

Ids are remembered. Every *_id a tool returns is stored and can be reused as $name in the next call, so a whole licensing negotiation can be typed without copying a single id by hand:

mcp> call buscar_pista {"mood": "epico", "instrumental": true, "presupuesto_max": 100, "limite": 3}
   ...
   remembered: $pista_id=TRK-00312

mcp> call verificar_clearance {"pista_id": "$pista_id"}

mcp> call calcular_costo_licencia {"pista_id": "$pista_id", "tipo_uso": "publicidad_online", "territorio": "latam", "exclusividad": "sectorial", "duracion_meses": 12}
   ...
   remembered: $cotizacion_id=COT-719E615733

mcp> call generar_contrato {"pista_id": "$pista_id", "cliente": "Agencia Lumen S.A.", "cotizacion_id": "$cotizacion_id"}
   ...
   remembered: $contrato_id=CTR-F9D1D72B0D

mcp> call registrar_uso {"contrato_id": "$contrato_id", "plataforma": "YouTube", "url_proyecto": "https://youtube.com/watch?v=demo"}

mcp> vars
mcp> quit

$pista_id defaults to the top candidate of the last search. Use vars at any point to see what is currently remembered.

6.3 Run the server on its own

python -m synclicense_mcp

It then waits for JSON-RPC messages on stdin. Use --catalog PATH to point it at a different catalog file.

6.4 Talk to it with no client at all

Because the transport is just newline-delimited JSON, you can drive the server straight from the shell:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"shell","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"verificar_clearance","arguments":{"pista_id":"TRK-00001"}}}' \
  | python -m synclicense_mcp

7. Tool reference

7.1 buscar_pista

Optional filters: mood, genero, instrumental, duracion_seg_min, duracion_seg_max, presupuesto_max, limite (1–20, default 5).

• mood: alegre, epico, melancolico, relajado, tenso, energetico, inspirador, oscuro

• genero: pop, rock, electronica, hip_hop, jazz, clasica, folk, ambient, cinematica, latina

Tracks blocked by an authorship dispute are excluded: they cannot be licensed, so offering them would be a false positive.

7.2 verificar_clearance

7.3 calcular_costo_licencia

Example request and response:

--> {"jsonrpc":"2.0","id":5,"method":"tools/call","params":{
      "name":"calcular_costo_licencia",
      "arguments":{"pista_id":"TRK-00312","tipo_uso":"redes_sociales",
                   "territorio":"local","exclusividad":"no","duracion_meses":6}}}

<-- {"jsonrpc":"2.0","id":5,"result":{
      "content":[{"type":"text","text":"Quote for TRK-00312 \"Stop!\" ... TOTAL USD 94.50"}],
      "structuredContent":{
        "ok":true,
        "cotizacion_id":"COT-3D18B1547D",
        "pista_id":"TRK-00312",
        "alcance":{"tipo_uso":"redes_sociales","territorio":"local",
                   "exclusividad":"no","duracion_meses":6},
        "desglose":{"tarifa_base_usd":94.5,
                    "multiplicadores":{"tipo_uso":1.0,"territorio":1.0,
                                       "exclusividad":1.0,"vigencia":1.0},
                    "subtotal_usd":94.5,"recargo_escrow_usd":0.0,
                    "total_usd":94.5,"moneda":"USD"},
        "valida_hasta":"2026-09-19T18:15:54+00:00"},
      "isError":false}}

7.4 Tool chaining

The tools are stateful within a session, which is the point of the use case:

buscar_pista ──► pista_id
                    ├──► verificar_clearance      (can stop the whole flow)
                    └──► calcular_costo_licencia ──► cotizacion_id
                                                        └──► generar_contrato ──► contrato_id
                                                                                     └──► registrar_uso

generar_contrato rejects a quote that does not exist, has expired (30 days), or was issued for a different track. registrar_uso rejects an unknown or inactive contract. Quotes and contracts belong to one connection and are not shared between sessions.

8. Pricing rules

subtotal = tarifa_base × mult_use × mult_territory × mult_exclusivity × mult_term
total    = subtotal + escrow surcharge (15% when the track has pending samples)

Six months is the reference term, which is why it sits at 1.0. A quote holds its price for 30 days.

9. Protocol details

Transport. stdio, one JSON-RPC 2.0 message per line, UTF-8, no embedded newlines. The server exits cleanly on EOF.

Protocol versions. 2025-11-25 (preferred) and 2025-06-18. If the client asks for anything else, the server answers with its preferred version instead of failing the handshake.

Methods.

Error codes.

Protocol errors vs. business errors. A malformed call comes back as a JSON-RPC error. A well-formed call that the licensing rules refuse — a blocked track, an expired quote, an unknown contract — comes back as a successful response carrying isError: true and a readable explanation, so a model can read the reason and correct course instead of seeing a transport failure.

A full specification is in docs/SERVER_SPEC.md.

10. Where the data comes from

Track metadata (title, artist, duration, genre, mood, licence, popularity ranking) comes from the public Jamendo API, which exposes a Creative Commons catalog. The catalog shipped in this repository was built that way. The offline generator produces the same shape locally, so the project still runs with no credentials and no network access.

The business layer is simulated, on purpose. No platform publishes its rate card or the internal legal status of each track, so tarifa_base_usd and estado_derechos are generated from a fixed seed with a realistic distribution (82% cleared, 13% samples pending, 5% blocked). The rate-card multipliers were designed from the public royalty-free rate cards of platforms such as Jamendo Licensing. This scope was reviewed and approved by the course instructor.

11. Testing

python -m pytest tests/ -v

The suite covers the rate-card rules, the JSON-RPC framing, the handshake, the error codes, the tool chain and its refusals, the seed generator, and one end-to-end test that launches the real server process and speaks the stdio transport to it. The tests look tracks up by rights status rather than by a fixed id, so they pass against any catalog: offline, Jamendo, or regenerated with a different seed.

12. Project layout

MCP-Local-Redes/
├── synclicense_mcp/          MCP server package (standard library only)
│   ├── __main__.py           entry point: python -m synclicense_mcp
│   ├── jsonrpc.py            JSON-RPC 2.0 framing over stdio
│   ├── server.py             MCP method dispatch
│   ├── tools.py              the five tools: schemas, validation, handlers
│   ├── pricing.py            conditional rate card
│   ├── contracts.py          contracts and usage registration
│   ├── catalog.py            catalog loading and search
│   └── errors.py             business-rule failures
├── client/mcp_cli.py         manual JSON-RPC client (demo + REPL)
├── scripts/seed_catalog.py   catalog builder (offline / Jamendo)
├── data/catalog.json         generated catalog
├── tests/                    pytest suite
└── docs/                     proposal, assignment brief, server specification

13. Project status

Delivered in this stage:

• Local MCP server over stdio with the five tools of the approved use case.

• JSON-RPC 2.0 and the MCP handshake implemented by hand.

• Command-line client with a scripted demo and an interactive REPL.

• Catalog seeding, in both offline and Jamendo modes.

• Test suite.

Planned for the rest of the project:

• Chatbot host on the Anthropic API, with session context and a visible log of every MCP interaction.

• Integration with the official Filesystem and Git MCP servers.

• The same server deployed remotely over HTTP.

• Wireshark capture and layer-by-layer analysis of the remote traffic.

Author: Esteban Cárcamo (23016) — CC3067 Redes, Section 20