Skip to content

Connect your AI agent

Already using Claude, ChatGPT, Claude Code or Cursor? Connect it to your ElfHosted stack and it can look after your apps with you. Ask it why something's slow, what's in your libraries, or to restart an app that's stuck, in the same chat you already use.

Your agent connects through ElfBot as an MCP server (the standard way AI agents plug into tools). It only ever sees your own apps, and it can't change anything without your OK.

No agent of your own?

You don't need one. Sam, the assistant in your dashboard, can do all of this and more, with nothing to set up.

What can it do?

Look things up, any time:

  • Which apps you have, whether they're healthy, and their recent uptime
  • How much CPU, memory, storage and bandwidth they're using
  • What's in your media, photo, book and music libraries, and what's been requested
  • Your JellyStreams profiles, and titles waiting for a parent's OK
  • The settings ElfHosted documents for each app, and which ones you've set
  • ElfHosted's docs, so its answers come from the real instructions

Ask for changes, which wait for your OK:

  • Restart or pause an app
  • Back up one app, or everything
  • Search for a missing movie or series in Radarr or Sonarr
  • Allow or decline a JellyStreams request
  • Change one of an app's settings

Full setup guide

The step-by-step setup is available to logged-in customers. Sign in to continue →

Connect it

  1. Open ElfBot at https://your-username-elfbot.elfhosted.com and click Connected agents
  2. Copy the Server URL shown under Connect an agent
  3. Add it to your agent:
    • claude.ai (and Claude Desktop and mobile): open Connectors (under Customize, or Settings on some plans), add a custom connector and paste the address. On a Team or Enterprise plan, an owner may need to add it first.
    • ChatGPT: add a custom MCP server (under Plugins, or in Settings with developer mode turned on, depending on your version), paste the address and choose OAuth. It needs a paid plan, and on a business plan your workspace admin may need to allow it.
    • Claude Code: run the claude mcp add command shown on the page, then type /mcp in a session to sign in.
    • Cursor: add the address as a remote MCP server in its MCP settings, and sign in when asked.
    • Anything else that can't sign in: make a token on the same page (see below) and give your agent the address and the token.
  4. When your agent sends you to ElfBot, sign in and allow it.

That's it. Try asking it something:

  • Is everything on my ElfHosted stack healthy?
  • Which of my apps is using the most memory?
  • Sonarr has a series with missing episodes. Can you search for them?
  • My Plex is stuck. Can you restart it?

How approvals work

Anything that changes something only asks. Here's what happens:

  1. Your agent asks for the change, and tells you it's waiting for your OK
  2. ElfBot sends you a notification (if you've turned them on) with a link to the request
  3. The approval page says, in ElfBot's own words, exactly what will happen and who asked
  4. You approve or decline. Your agent checks back and tells you how it went.

Only you can approve, signed in with your ElfHosted login. If a change needs a password or API key, you type it on the approval page itself: your agent never sees it. Never paste a password or key into the chat. If you do, change it where it came from.

Some actions, such as setting up streaming sources or changing an app's settings, ask you to agree to ElfHosted's Acceptable Use Policy and Terms of Service first. You type I agree once, and you're only asked again if the wording changes.

Tokens for other agents

Agents that can't sign in use a token instead. On the Connected agents page, under Make a token:

  • Give it a name you'll recognise later, like Claude Code on my laptop
  • Choose what it may do: Looks things up, or Looks things up and asks for changes
  • Choose when it expires: 30 days, 90 days, a year, or never

The token is shown once, so copy it straight away. You can have up to 10.

Keep an eye on it

The Connected agents page lists every agent and token, with when each was last used and roughly where from (its address and country). If you don't recognise one, or you've finished with it, revoke it there: it stops working straight away.

What it can't do

  • It can't see anyone else's stack, only yours
  • It can't read your files or your apps' logs. For logs, ask Sam.
  • It can't reach ElfHosted's team for you. When a human should look, have it write up what it found, and bring that to #elf-help yourself.

See also: Sam, ElfBot and getting help.