One self-hosted app for your shows, movies and music.
title: AI apps description: Connect Claude, ChatGPT, Cursor and other MCP apps to HolyArrs, and what app makers need to know. level: Expert sidebar: { order: 4 }
Ask an AI app "what's downloading?" or have it request a movie, over MCP.
:::caution
AI apps are held back in this release. You see them only when the ai_apps feature is switched on.
:::
Connect an AI app
- Open Settings > AI apps on the same address your AI app will use. The page builds the steps from the address in your browser.
- Switch on Let AI apps connect. Only the owner can.
- Under Connect an AI app, pick your app and follow its steps.
- Ask your app: "What's downloading in HolyArrs?" You should see it under Linked AI apps with a last used time.
Or click Or let your agent do it and paste the short prompt into a coding agent. If the prompt holds a key, paste it only into your own agent.
The AI address is your HolyArrs address plus /api/v1/mcp, such as http://your-server:6262/api/v1/mcp. /mcp works too. Under a URL base, put the base first.
Choices
Browser sign-in or AI key
| Way | How | Needs |
|---|---|---|
| Browser sign-in | Add the address; the app opens HolyArrs, you click Allow. The app gets its own key. | https, or the app on the same computer (localhost) |
| AI key | Click Make a key next to your app, copy it once into the config shown. | Any address |
| You open HolyArrs on | Apps on your computer | Cloud apps (Claude app, ChatGPT, Gemini app, Grok, Perplexity) |
|---|---|---|
A public https name |
Browser sign-in | Browser sign-in |
An https name only your devices reach |
Browser sign-in | Can't reach it |
localhost |
Browser sign-in | Can't reach it |
Plain http, such as http://your-server:6262 |
AI key | Can't reach it |
The page can't tell whether an https name is open to the internet, so it may show cloud steps that won't work on a home-only name. Claude Desktop can reach a home address through the mcp-remote bridge, which needs Node.js.
Keep an AI key out of links and chats; it belongs in the app's config. AI keys work only on the AI address, and ordinary API keys don't work there.
Where each app takes the address
Settings > AI apps shows these steps with your address filled in. Any other app that adds a remote MCP server works too.
| App | Where you add HolyArrs | On plain http |
|---|---|---|
| Claude app | Connectors, add custom connector | Can't reach it |
| ChatGPT | Add custom MCP server | Can't reach it |
| Gemini app | Custom connected app | Can't reach it |
| Grok | Connectors, custom | Can't reach it |
| Perplexity | Add MCP connector, remote | Can't reach it |
| Claude Code | claude mcp add |
AI key |
| Codex | codex mcp add |
AI key |
| Cursor | ~/.cursor/mcp.json |
AI key |
| VS Code | MCP Servers, Add Server | AI key |
| Gemini CLI | gemini mcp add |
AI key |
| Claude Desktop at home | Developer config, through mcp-remote |
AI key |
| Open WebUI, LM Studio | The app's MCP settings | AI key |
Getting an https address
For cloud apps or browser sign-in from another computer: a reverse proxy with a certificate, Cloudflare Tunnel (public, no open port), Tailscale Serve (your devices only) or Tailscale Funnel (public). Then:
- Add the name to
HOLYARRS_ALLOWED_HOSTS. - Add the proxy to
HOLYARRS_TRUSTED_PROXIESand sendX-Forwarded-Proto: https. Without it, HolyArrs hands outhttpsign-in addresses and apps refuse them.
:::caution Cloud apps need HolyArrs with no login screen in front, which puts your sign-in page on the internet. Use a strong password and two-factor sign-in. :::
What an app can do
It acts as the person who connected it, with their permissions, request limit and kid account limits.
| Tool | Does | Shown when |
|---|---|---|
search_titles |
Finds movies and shows from plain words | Movies, TV shows or Music is on |
library_lookup |
Checks if a title is in the Library | Movies, TV shows or Music is on |
calendar |
What comes out in 1 to 60 days (default 14) | Movies, TV shows or Music is on |
downloads |
What is downloading and how far | Always |
my_asks |
Your requests and how many more you may make | Requests is on |
health |
Whether HolyArrs and its apps work | The person may manage the Library |
ask_for_title |
Requests a movie or show, after you agree | Requests is on and the person may request |
Only ask_for_title changes anything. It counts as your own request. An app can't approve requests, change settings, people or keys, see others' requests, or delete or move files.
If it does not work
| Symptom | Fix |
|---|---|
| 404 or "not found" | Switch on Let AI apps connect. Check the address ends in /api/v1/mcp. |
| 401 or "sign in" | Key missing, revoked or its account is off. Sign in again from the app, or make a new key. |
403 about the mcp scope |
The app sent an ordinary API key. Make an AI key. |
Sign-in refused on plain http |
Use Make a key, or reach HolyArrs over https or localhost. |
| Sign-in fails behind a proxy | Set HOLYARRS_TRUSTED_PROXIES and send X-Forwarded-Proto: https. |
| "request from another site or host name refused" | Add the name to HOLYARRS_ALLOWED_HOSTS. |
| "This AI app is not registered with HolyArrs." | Remove HolyArrs from the app and add it again. |
| "Sign in with your password to manage AI keys." | Sign out and back in with your password, or ask the owner. |
| A tool is missing | Check the person's permissions and which parts are on. |
| "too many calls from this key" | Wait the seconds shown. |
| "that confirm_token is unknown, used or expired" | Ask the app again. |
| The app never uses HolyArrs | The model may be too small for tools. Try a bigger one. |
For experts
Linked AI apps and History
- The card lists each AI key: name, last 4 characters, made and last used.
- Revoke stops an app at once. Make a key by hand names a key for apps not in the list.
- The owner sees every AI key; others who may change settings see their own. Managing keys needs that permission and a recent password sign-in.
- A key stops working when its account is turned off.
- While Let AI apps connect is off, a keyed app gets not found; an app without a key is still sent to sign in. The owner clicking Allow turns it on.
- In Downloads > History, set Who to AI apps. Requests show as By AI with the app and person; refused ones as Not done with the reason. Look-ups are not written.
Config shape for other apps
{
"mcpServers": {
"holyarrs": {
"url": "http://your-server:6262/api/v1/mcp",
"headers": { "Authorization": "Bearer <your AI key>" }
}
}
}
With browser sign-in, leave out headers.
For app makers: transport and addresses
MCP over Streamable HTTP: one JSON-RPC 2.0 message per POST, answered as JSON in the same response. No event stream; GET answers 405. Protocol versions 2025-11-25, 2025-06-18, 2025-03-26. Messages up to 64 KB.
| What | Address |
|---|---|
| AI address | POST /api/v1/mcp (also /mcp) |
| Protected resource metadata | GET /.well-known/oauth-protected-resource/api/v1/mcp |
| Sign-in server metadata | GET /.well-known/oauth-authorization-server |
| Register an app | POST /oauth/register |
| Start sign-in | GET /oauth/authorize |
| Get the key | POST /oauth/token |
Under a URL base, every address starts with the base.
For app makers: keys, sign-in and limits
Send Authorization: Bearer <key> or X-Api-Key: <key>.
| Case | Answer |
|---|---|
| No key | 401, WWW-Authenticate pointing to the protected resource metadata, scope mcp |
| Wrong or revoked key | 401, error="invalid_token" |
Key without mcp scope |
403 |
| AI apps off, valid AI key | 404 |
Origin naming another host |
403 |
| Over 60 calls a minute or 5 requests an hour per key | 429 with Retry-After, JSON-RPC error -32000 |
- Registration is open:
client_nameand 1 to 10redirect_uris, eachhttps,httpon loopback, or the app's own scheme. Apps are public, with no client secret. - Authorization code with PKCE
S256(required). The only scope ismcp. The person clicks Allow on/ai. - The code works once, for 5 minutes. The
access_tokenis the app's AI key: no expiry, no refresh token, valid until revoked. ask_for_titletakes 2 calls: the first returns a summary and a confirm token the app must show you; the second sends the token. It works once, for that title, for 5 minutes. Lists are cut to 25 items.