MCP Tool Reference

MCP Tool Reference

Orynivo exposes 23 tools. External clients call them through the shared MCP endpoint documented in AI-Chat-and-MCP. The embedded AI chat uses the same tools directly inside the application.

Arguments marked required must be supplied.

Player state and transport

Tool	Arguments	Result or effect
get_now_playing	None	Returns the current track and playback state. Credential-bearing values are redacted.
get_current_time	None	Returns local and UTC date/time, weekday, and time-zone information.
play	path: absolute local path or orynivo:// reference	Plays the item. Omitting path resumes the current item.
pause_resume	None	Toggles pause and resume.
next_track	None	Advances to the next queue entry.
previous_track	None	Returns to the previous queue entry.
stop	None	Stops playback.
seek	positionSeconds: number	Seeks to an absolute position in seconds.
set_volume	volume: number from 0 to 1	Sets player volume.

Example:

{
  "name": "seek",
  "arguments": {
    "positionSeconds": 90
  }
}

Queue

Tool	Arguments	Result or effect
get_queue	None	Returns the queue with credential-bearing values redacted.
queue_append	path: local path or orynivo:// reference	Adds an item at the end.
queue_play_next	path: local path or orynivo:// reference	Inserts an item after the current item.
clear_queue	None	Clears upcoming entries without stopping the current track.
replace_queue	paths: array of paths or references	Replaces the queue and starts its first item.

Example:

{
  "name": "replace_queue",
  "arguments": {
    "paths": [
      "D:\\Music\\Album\\01 - Intro.flac",
      "D:\\Music\\Album\\02 - Song.flac"
    ]
  }
}

Library

Tool	Arguments	Result or effect
search_library	query: string; limit: integer 1–50, default 10	Searches the local library and every configured Orynivo Server.

Remote tracks are returned as stable references:

orynivo://serverId/track/123

Pass a returned reference unchanged to play, queue_append, queue_play_next, or replace_queue. Orynivo resolves authentication internally.

{
  "name": "search_library",
  "arguments": {
    "query": "Roads Portishead",
    "limit": 5
  }
}

Playlists

Tool	Arguments	Result or effect
list_playlists	None	Lists available playlists.
get_playlist_tracks	playlist: name or numeric ID	Returns the entries of a playlist.
create_playlist	name: string; paths: optional comma-separated local paths	Creates a regular playlist.
create_smart_playlist	name plus optional criteria below	Creates a dynamically resolved smart playlist.

Smart-playlist criteria:

Argument	Type	Meaning
favoritesOnly	Boolean	Include only favourites.
genres	Comma-separated string	Match one or more genres.
artistContains	String	Match artist text.
albumContains	String	Match album text.
addedWithinDays	Integer	Include tracks added within this many days.
neverPlayed	Boolean	Include only tracks without playback history.
sortOrder	String	title, random, recent, or leastrecent.
resultLimit	Integer	Limit the number of tracks.

{
  "name": "create_smart_playlist",
  "arguments": {
    "name": "Recent electronic favourites",
    "favoritesOnly": true,
    "genres": "Electronic,Trip-Hop",
    "addedWithinDays": 90,
    "sortOrder": "recent",
    "resultLimit": 50
  }
}

Playback history

Tool	Arguments	Result or effect
get_play_history	date: YYYY-MM-DD; limit: integer 1–100, default 20	Returns entries for a local calendar date, or the latest entries if no date is supplied.

Web

Tool	Arguments	Result or effect
search_web	query: string; maxResults: integer 1–25, default 5	Searches through the configured SearXNG instance.
fetch_page	url: HTTP or HTTPS URL	Returns guarded, extracted readable text.
fetch_page_as_markdown	url: HTTP or HTTPS URL	Returns guarded, extracted Markdown.

The web tools require a valid web-browsing configuration. Page retrieval is subject to destination, redirect, timeout, content-type, and response-size restrictions described in AI-Chat-and-MCP#web-browsing-endpoints.

Error behaviour

• A tool disabled in Settings returns Tool is disabled..
• Missing or invalid arguments produce a tool error for the calling model or MCP client.
• Playback can fail if a path no longer exists, a remote server is unavailable, or the selected format/output path cannot be opened.
• The SSRF guard may refuse a URL even when the configured search engine returned it.
• Tool results are application data and should not be treated as trusted model instructions.