AI Chat and MCP

AI Chat and MCP

Orynivo offers two related integrations that share the same tool implementation:

1. The embedded AI chat sends OpenAI-compatible chat-completion requests to a configured model provider. Tool calls are executed directly inside Orynivo.
2. The optional MCP server allows an external MCP client to use Orynivo's player, library, queue, playlist, history, and web tools.

The embedded chat does not connect to Orynivo through MCP. It calls the same tools in-process.

Endpoint overview

Purpose	Method and endpoint	Notes
MCP	MCP over HTTP at http://localhost:{port}/mcp	Default port: 49200; inbound connection from an MCP client
AI chat	POST {EndpointUrl}/chat/completions	Default base URL: http://localhost:1234/v1; outbound request from Orynivo
SearXNG search	GET {SearxngUrl}/search?q=…&format=json&safesearch=1	Used by search_web
Page retrieval	GET {requested-url}	Used by both page-fetch tools and protected by SSRF checks

If the configured AI endpoint already ends in /chat/completions, Orynivo uses it unchanged. Otherwise, it removes a trailing slash and appends /chat/completions.

MCP server

Enable the server under Settings → Integration → MCP Server. Its default address is:

http://localhost:49200/mcp

The port can be changed in Settings. Orynivo binds exclusively to localhost, so the endpoint is not exposed to other computers on the network.

There is no separate URL for each tool. MCP clients list and call tools through the shared /mcp endpoint. A URL such as http://localhost:49200/play therefore does not exist.

A generic URL-based MCP client configuration looks like this:

{
  "mcpServers": {
    "orynivo": {
      "url": "http://localhost:49200/mcp"
    }
  }
}

The exact property names differ between MCP clients. Select the client's HTTP-based MCP transport, not a command-based stdio server.

The server identifies itself as Orynivo version 1.0. Individual tools can be disabled in Settings. A disabled tool returns Tool is disabled..

See MCP-Tool-Reference for all 23 tools, their arguments, and examples.

Embedded AI chat endpoint

Configure the provider base URL, optional API key, model name, and maximum token count under Settings → Integration → AI Chat. With the default base URL, Orynivo sends requests to:

POST http://localhost:1234/v1/chat/completions
Content-Type: application/json

When an API key is configured, the request additionally contains:

Authorization: Bearer <API key>

The request uses the OpenAI-compatible chat-completions format:

{
  "model": "configured-model-name",
  "messages": [
    {
      "role": "user",
      "content": "Play something by Portishead"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "search_library",
        "description": "Search the music library",
        "parameters": {}
      }
    }
  ],
  "stream": true,
  "max_tokens": 2048
}

The real request contains the complete schemas described in MCP-Tool-Reference. The abbreviated tool schema above only illustrates the surrounding request structure.

Orynivo reads the response as server-sent events. Each event is expected as a data: line containing a chat-completion chunk; data: [DONE] ends the stream.

When the model requests tools, Orynivo:

1. collects the streamed tool name and JSON arguments;
2. executes the tool inside the running player;
3. adds the result to the conversation;
4. sends the updated conversation back to the model; and
5. repeats until the model produces a final response.

Settings are read again for every message, so changing the endpoint, model, key, or token limit does not require restarting Orynivo. Clear removes the visible conversation and resets the internal chat history.

Web browsing endpoints

The three web tools are optional:

• search_web queries the configured SearXNG JSON API.
• fetch_page returns extracted readable text.
• fetch_page_as_markdown returns extracted Markdown.

For example, with https://search.example.org configured as the SearXNG URL, a search for lossless audio is sent to:

GET https://search.example.org/search?q=lossless%20audio&format=json&safesearch=1
Accept: application/json

The explicitly configured SearXNG service may run on the local network. URLs returned by it are not trusted automatically: page fetching accepts only HTTP and HTTPS and validates every destination and redirect.

Safeguards include:

• blocking loopback, private, link-local, and reserved IP addresses;
• protection against DNS rebinding at connection time;
• a bounded number of redirects;
• request timeouts and response-size limits;
• refusal of non-text downloads; and
• an audit log in Orynivo's local logs directory.

An optional domain allowlist can further restrict page fetching.

Security and privacy

• MCP listens on localhost only. It has no separate authentication layer, so other processes running locally may attempt to connect while it is enabled.
• Remote Orynivo tracks use opaque orynivo://serverId/track/trackId references. Authentication is resolved internally only when playback or queueing is requested.
• Credential-bearing URLs are redacted in queue and now-playing tool results.
• Plex tokens and Orynivo Server API keys must not be copied into prompts or MCP client configuration.
• The configured AI provider receives the conversation, tool definitions, and tool results required for the tool loop. Select it according to your privacy requirements.