Morgen Commander's API and MCP server

From 1.3.0, programs and AI assistants on your computer can drive an avatar logged in to Morgen Commander (MC): read and answer chat and IMs, follow everything that arrives as it happens, answer offers, script menus and permission requests, teleport, turn, run gestures and animations, and log the avatar in and out. It's off until you switch it on, and each avatar needs a token you make for it.

There are two ways in, both served by MC itself:

Both do the same things with the same commands, and both go through the same code as MC's keys, so everything a program does shows in MC's window, RLV's limits apply, and chat is logged as usual.

Quick start
  1. Save the avatar's login. Log it in once in MC with Remember password ticked. Programs log in with that saved login; they never see or send a password. (No window, on a server? See Headless.)
  2. Switch the API on. Session → Preferences → API: tick Let programs and AI assistants drive avatars through MC.
  3. Make a token. Choose the avatar, press Make a token, and tick what it may do (see Permissions).
  4. Copy what you need, then press OK. The token, a ready-made line for Claude Code and a ready-made entry for Claude Desktop show once, with the token filled in. MC keeps only a fingerprint of it, so copy it now. The token works from the moment you press OK.
  5. Connect your assistant or script as below, and try status.
Connecting an AI assistant

Claude Code

Run the line Preferences shows in a terminal. It looks like this (for an avatar called Pixel Moonbeam):

claude mcp add --transport http mc-pixel http://127.0.0.1:47174/mcp --header "Authorization: Bearer mc_…"

That adds MC to the project you run it in. Add --scope user after add to have it in every project. Then claude mcp list should say mc-pixel … Connected, and a new Claude Code session has the avatar's tools.

Claude Desktop

Claude Desktop starts its MCP servers itself and talks to them over their input and output. MC does that with MorgenCommander --mcp: it opens no window, and passes everything on to the MC that's already running (so MC must be running, with the API on).

Open Claude Desktop's config file (Settings → Developer → Edit Config):

The whole file must be one JSON object, with your servers inside mcpServers. Preferences shows the file as it should be with just this avatar in it (1.3.0 showed only the part from "mc-pixel" on):

{
  "mcpServers": {
    "mc-pixel": {
      "command": "C:\\Users\\you\\AppData\\Local\\Programs\\Morgen Commander\\MorgenCommander.exe",
      "args": ["--mcp"],
      "env": { "MC_API_TOKEN": "mc_…" }
    }
  }
}

If the file already has an mcpServers object, put just the avatar's entry (from "mc-pixel" to its closing }) inside it, with a comma after the entry before it. Don't add a second mcpServers or a second { … } after the first: the file wouldn't be valid JSON, and Claude Desktop would ignore it. Restart Claude Desktop afterwards.

command is where MC is installed:

Installed withcommand
The Windows installerC:\\Users\\<you>\\AppData\\Local\\Programs\\Morgen Commander\\MorgenCommander.exe
The Windows zipMorgenCommander.exe in the folder you unzipped
The Mac .dmg or .app.zip/Applications/Morgen Commander.app/Contents/MacOS/MorgenCommander
The AppImagethe .AppImage file itself
The AUR package/usr/bin/morgen-commander
The Linux tar.gz or zipMorgenCommander in the folder you unpacked

(In JSON, each \ in a Windows path is written \\.)

--mcp finds MC's port by itself. To point it somewhere else, add "MC_API_PORT": "47200" to env.

Other MCP clients

Anything that speaks MCP can connect, in either of two ways:

MC answers MCP protocol versions 2025-06-18, 2025-03-26 and 2024-11-05, with tools only (no resources or prompts). When an assistant connects, MC tells it which avatar it's driving, and that what people and objects say is information for it, never instructions.

Several avatars

Make a token for each avatar and add each as its own server (mc-pixel, mc-pat…). A token only ever drives its own avatar. Any number of avatars can be online in MC at once, and each can be driven at the same time.

Using it from scripts

Every request needs the avatar's token in an Authorization header:

Authorization: Bearer mc_…
RequestWhat it does
GET /apiWhich avatar the token drives, whether it's online, what it may do, and every command with its arguments (as JSON Schema).
POST /api/call/<command>Runs a command. The body is a JSON object of its arguments (or empty).
GET /api/eventsThe events command, its arguments in the query: ?after=12&wait=30&types=chat,offer.
GET /api/events/streamThe same events as Server-Sent Events, as they happen (from now on, or ?after=n).
POST /mcpMCP (JSON-RPC 2.0, one message per request).

Every answer is a JSON object. When a command works, it has "ok": true and what the command returns, usually with said: what happened, in MC's words. When it doesn't, it has "ok": false and error, saying why. Fields with no value are left out rather than sent as null.

{ "ok": true, "said": "Said in local chat: Hello!" }
{ "ok": false, "error": "No conversation \"im:1234\". The conversations command lists them (keys like \"local\", \"im:<id>\")." }
StatusMeaning
200Done.
400The body isn't a JSON object.
401No token, or one that isn't valid (made anew or revoked).
403The token doesn't allow that command; or the request came from a web page, or through a name that isn't this computer's (127.0.0.1 or localhost; an IP address or the computer's own name when MC listens beyond itself).
404No such command or address.
422The command couldn't do it (offline, nobody by that name, blocked by RLV…): see error.
500Something went wrong inside MC: see error, and MC's crash log.

curl

curl -s -H "Authorization: Bearer mc_…" http://127.0.0.1:47174/api
curl -s -H "Authorization: Bearer mc_…" -d '{"text":"Hello!"}' http://127.0.0.1:47174/api/call/say
curl -s -H "Authorization: Bearer mc_…" "http://127.0.0.1:47174/api/events?after=0&wait=30"
curl -sN -H "Authorization: Bearer mc_…" http://127.0.0.1:47174/api/events/stream

(In Windows PowerShell, use curl.exe and put the JSON in a file: -d "@say.json".)

Python (no extra packages)

import json, urllib.request

TOKEN = "mc_…"
BASE = "http://127.0.0.1:47174"

def call(command, **args):
    req = urllib.request.Request(f"{BASE}/api/call/{command}", data=json.dumps(args).encode(),
                                 headers={"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"})
    try:
        with urllib.request.urlopen(req, timeout=90) as r:
            return json.load(r)
    except urllib.error.HTTPError as e:      # 4xx and 5xx still carry {"ok": false, "error": …}
        return json.load(e)

print(call("status"))
print(call("say", text="Hello from Python!"))

# Follow what arrives, answering IMs.
after = call("status")["last_event"]
while True:
    got = call("events", after=after, wait=50)
    after = got["next_after"]
    for e in got["events"]:
        if e["type"] == "chat" and e["conversation_kind"] == "im" and not e["own"]:
            call("send", conversation=e["conversation"], text="Thanks, I'll be back soon.")

Finding the port

MC writes where it listens to api.json in its data folder while the API is on (no token in it), and removes it when MC closes:

{"port":47174,"address":"127.0.0.1","host":"127.0.0.1","mcp":"http://127.0.0.1:47174/mcp","api":"http://127.0.0.1:47174/api"}

address (1.5.4) is the address MC listens on, and host where a program on the same computer reaches it: 127.0.0.1 unless MC listens on one particular address of the computer.

Listening beyond this computer

MC listens on 127.0.0.1 unless told otherwise, so only programs on the same computer can reach it. From 1.5.4 the Address in Preferences → API (or --address for headless MC) changes that:

Other computers then use this computer's address or name in place of 127.0.0.1, with a token as always: http://192.168.1.20:47174/mcp. MC still refuses requests from web pages, and any that come through a name that isn't an IP address or this computer's own (its host name, with .local or its domain), since a web page could reach MC through a domain of its own. A proxy in front of MC should pass the address it connects to as Host (nginx does by default; in Caddy, header_up Host {upstream_hostport}).

MC's API is plain HTTP: tokens, and everything the avatar reads and says, cross the network unencrypted. Use this only on a network you trust, or through a VPN (WireGuard, Tailscale…), or keep 127.0.0.1 and forward the port over SSH (ssh -N -L 47174:127.0.0.1:47174 you@that-computer). The computer's firewall may ask whether MC may listen, or need the port opened.

The beta grid (1.5.0): MC started with --beta-grid logs in to Second Life's beta grid (Aditi) and keeps its own data folder (beta grid inside the usual one), with its own tokens, and listens on 47184 by default, so it can run beside the main grid's MC. status says which: grid is main or beta. An MCP client starting MC as a stdio server gives --mcp --beta-grid.

Permissions

Each avatar's token has its own permissions, ticked in Preferences → API. A program only sees the commands its token allows (an assistant's tool list leaves out the rest), and a command outside them answers 403.

Permission (--allow)CommandsOn for new tokens
Log in and out (login)login, logoutyes
Read (read)status, conversations, read_chat, events, find_person, nearby, radar_borders, outfit, friends, profile, groups, find_group, group_info, group_members, group_roles, group_notices, read_notice, find_place, place, parcel, land, stream, places, nearby_objects, object_info, object_contents, hud_parts, blocked, outbox, transactions, rlv, pending, gestures, check_updateyes
Chat (chat)say, send, send_im, send_group, typing, start_conference, join_group_chat, close_conversation, edit_outboxyes
Answer prompts (prompts)answer, take_notice_attachmentyes
Move (move)teleport, set_home, stand, face, walk, run_gesture, set_gesture, play_animation, stop_animation, touch_object, sit_on_object, touch_hud, label_hud_button, forget_hud_buttonyes
See inventory (inventory_read)list_folder, find_items, read_text, changes, wearing, notecard_items, view_texture, report, find_duplicates, filing_rules, saved_searches, run_saved_search, pending_changes, cleanup_list, read_object_text, view_object_texture, view_hud_faceno
Inventory changes (inventory; includes seeing it)make_folder, make_item, link, make_landmark, rename, set_properties, move, copy, delete, write_notecard, write_script, copy_from_notecard, run_filing_rules, settle_changes, undo, wear, take_off, reorder_layer, edit_cleanup, take_object, delete_object, return_object, copy_from_object, copy_to_object, set_script_running, set_object_item_properties (and seeing the inventory)no
Social (social)give, offer_teleport, request_teleport, offer_friendship, end_friendship, friend_rights, block, unblock, join_group, leave_group, set_group_tag, invite_to_group, group_settings, send_notice, set_charter, save_role, delete_role, block_objectno
L$ (money)pay, pay_object, buy_object, within the limits set beside it: per payment and per dayno
Update MC (update)update_self: install a new version of MC and restart itno
Let go of RLV (rlv_release)release_rlv: release the restrictions an attachment or relay holds, as F8 in the RLV folderno
Land (land; 1.6.0)set_land, land_list, return_land_objects: change the parcel the avatar is on, where it may; play_stream (1.6.1): parcel music in MC's windowno

L$ limits (1.3.3): with L$ ticked, set how much a program may pay at a time and in a day. Both have to be more than 0, or programs can't pay at all; a payment over either, or over the balance, is refused. What programs have paid today is kept in MC's data folder, so restarting MC doesn't reset it. Programs pay people only, never objects, and never pay a group's joining fee.

Flood limits (1.3.2): programs get at most so many IMs (and group, conference and object lines) and so many local chat lines a minute from any one sender, 6 and 10 unless you change them (0: no limit). The rest are held back from programs, with a flood event saying so, so nobody can run up an AI's usage by spamming it. MC itself still shows and logs every line, and the avatar's own lines always reach programs.

Log in when needed (off unless ticked): a command that needs the grid while the avatar is offline logs it in first, instead of answering "Offline: log in first".

Nothing a program does waits for a click in MC: what's ticked, it just does. Whatever is ticked, a program can never empty the Trash, delete anything for good, let a script take L$ (it can refuse such a request, never grant it), see or change passwords, change Preferences or tokens, pay past the L$ limits, or pay objects or joining fees. RLV's limits apply to programs exactly as they do to the keys; only Let go of RLV, which is never on unless ticked (--allow all leaves it out too), lets a program release what an attachment holds, as F8 in the RLV folder does.

Changed permissions apply as soon as you press OK. An assistant that's already connected may need reconnecting to see its new list of tools.

Commands

Arguments marked * are needed. Names are always as the grid gives them: a command that's given a name finds the person or group by it, and when several match, it says so and lists them rather than guessing.

Session

status: works offline too. Answers avatar, online, last_event (the newest event number, for events); and when online: name, id, region, parcel, position (x, y, z), slurl, facing ("south (179°)"), sitting, balance (L$), unread (ims, groups), pending_prompts, rlv (whether RLV is on for the avatar). Always, mc: MC's own version, build, os, platform and mode (window or headless), and update, what MC knows of a newer version (see MC itself). GET /api has mc too.

login: logs in with MC's saved login.

ArgumentTypeMeaning
startstringlast (the default), home, or a region name.
forcebooleanLog in even if the avatar is online in another viewer on this computer (that one is logged out).

It stops, saying why, when there's no saved password, when the account wants a second-factor code or new terms accepted (log in once in MC's window to deal with those), or when the avatar is online in another viewer here. Answers said ("Logged in, in Schplitz."), online, region.

logout: logs the avatar out, without MC's "Log out?" question.

Chat

Conversations have keys: local (local chat), im:<their UUID>, group:<group UUID>, conf:<session UUID> (conferences), objects (messages from objects), and rlv (1.4.2: with RLV on, the commands the avatar's HUDs and relays send, MC's answers and what it did, and what those objects say to it, which no longer comes in local chat). local, objects and rlv can always be read, even before anything has been said in them. An object with no name shows as "(unnamed object)". An object's line has object: true and, when the grid says, owner_id (1.4.2); its from_id is the object (for an object's IM too, since 1.4.2: it was the owner).

conversations: the open ones, each with key, kind, title, unread, silenced, lines, and typing (who's typing there now, when anyone is: IMs and local chat only).

chat_members (1.4.2): conversation* (a group chat or conference), max (default 100). Answers in_chat: everyone the grid lists as in it and everyone who has spoken in it this session (each id, name, display); for a group, also online_in_group: its other members online now (asked of the grid at most every five minutes), with more when there were more than max.

read_chat: lines of one conversation, oldest first.

ArgumentTypeMeaning
conversation*stringIts key.
linesintegerHow many of the newest lines (default 30, at most 200).
sincestringOnly lines after this time (ISO 8601: 2026-10-12T18:00:00Z).
mark_readbooleanClear its unread count, as reading it in MC does.
earlierintegerAlso this many lines from earlier sessions (default 0, at most 200).

Answers conversation, title, unread, more_before (older lines are there), and lines, each with time, from_id, from_name, from_display (the name as MC shows it), text, own (the avatar said it), and when they apply, object (an object said it), volume (whisper or shout) and notice (nobody said it: MC's "is online.", or the grid's own words in an IM, such as "User not online - message will be stored and delivered later.", which come from Second Life with the null UUID as from_id).

With earlier, the answer also has earlier: the newest lines from before this session, from MC's chat log, as the chat window shows them above this session's. Each has time and text, the line as logged ("Pixel Moonbeam: hi"). That works for an IM (im:<id>) or one of the avatar's group chats (group:<id>) that isn't open now, too.

say: local chat.

ArgumentTypeMeaning
text*stringWhat to say.
channelintegerA channel for scripts and HUDs (default 0, open chat).
volumestringnormal (20 m, the default), whisper (10 m) or shout (100 m).
typedbooleanAs if typed in MC's chat window: /me, /shout, /whisper, /5 and gesture triggers.

Without typed, the text goes exactly as given. With it, the text is taken as the chat window takes it: gesture triggers fire, and /me, /shout, /whisper and a channel (/5 hello) work. Since 1.7.1 the chat window is for chat only, and MC's other commands (/face, /anim, /tp, /pay, /swap…) are refused with typed: programs have their own (face, play_animation, teleport, send_im…).

send: a reply in a conversation that's already there. conversation* (its key), text*.

send_im: an IM to anyone. to* (their UUID, or exact name: "Pixel Moonbeam" or "pixel.moonbeam"), text*. Answers conversation (its key, for send and read_chat from then on), to_id, to_name. Second Life carries at most 1023 bytes in one IM, so longer text arrives as more than one message. When the person is offline, the grid answers with a notice line in the IM ("User not online…"), and the IM waits for them.

While the avatar is logged out (and the token doesn't log in when needed), send_im puts the IM in the avatar's Outbox instead, as the window does for an IM written while logged out. It goes at the avatar's next login, once RLV has had a minute to restate its limits. The answer then has queued: true and outbox_id. Offline, to has to be a UUID or the name of one of the avatar's friends (MC keeps the friend list between logins).

outbox: the IMs waiting there, each with id, to_id, to_name, text, written. edit_outbox: id*, and the new text, or cancel: true. Both work offline too.

send_group: to one of the avatar's group chats. group* (its UUID, its name, or a part of the name that only one group has), text*.

start_conference: a conference (a group IM) with two or more people. people* (their UUIDs or exact names, separated by commas). Answers conversation, its key.

join_group_chat: opens one of the avatar's group chats, so its lines come to events and read_chat. group* (as for send_group, which opens it too). Answers conversation.

close_conversation: closes one, as the chat window's Close tab. conversation* (its key; local chat and object messages are always there). A group chat is left too, until someone there speaks again (the chat window's /leave).

typing: show the avatar typing in an IM or local chat while you work out a reply. conversation* (im:<id> or local), on (true, the default, or false to stop), seconds (at most; default 60, from 1 to 120: outside that, or the all-zeros UUID, is an error since 1.4.5). It stops by itself when you send there. You rarely need it: when events (or the event stream) hands a program that may chat a new IM, MC shows the avatar typing in it until the program answers there, or for a minute. Both only when the avatar's settings let others see it typing (Preferences → Chat).

events: see Events.

People

find_person: looks people up on the grid, as a viewer's Search window does. name* (a name, or a word in one: Pixel Moonbeam, pixel.moonbeam, commander), max (default 100, at most 300). It searches account names (usernames and legacy names), not display names. Answers people, each with id, name, display, the name itself first, then names starting with it, then the rest; and more: true when there were more than it gave.

nearby: people in the region, nearest first, each with id, name, display, distance (meters), height_known (false when the region only gives a rough height, so the distance is rough too), and hears: how quietly the avatar can speak and still be heard by them (whisper, talk, shout, or no when they're too far even for a shout). From 1.5.4, borders says whether the radar reaches across region borders; while it does, people in the neighboring regions within 100 m (as far as a shout carries) are listed too, each with region (the neighboring region they're in), and neighbor_regions lists the regions heard from. RLV's @showloc leaves the region names out.

radar_borders (1.5.4): on (true or false) switches the radar across region borders, for every avatar, as Preferences → Radar, /radar borders on and right-clicking the radar do; without on it only says. Answers on. MC connects to the neighboring regions for it, as graphical viewers do: more traffic, and chat from across the border is heard too (chat events, as any local chat).

outfit (1.5.3): who* (someone in the region: their UUID, or the start of their name). What they're wearing, as the region shows it to everyone: attachments, each with point ("Skull", "Left Hand"), name, description, creator and creator_id, object_id, and (1.5.4) touchable: whether it answers touches (touch_object with its object_id touches it). HUDs and clothing layers show to nobody else, so they aren't there. The region describes attachments only within view (about 128 m): for someone further away the list is empty and note says why. The first time, the details are fetched from the grid, which takes a few seconds; they're kept 15 minutes. A name of null means the grid hasn't answered for that one yet; asking again may fill it in. RLV's @shownames and @shownearby refuse it.

friends: each with id, name, display, online; online ones first.

profile: who* (UUID or exact name). Answers id, name, display, born, partner, about, first_life, image and first_life_image (the pictures' texture UUIDs, or null; 1.4.4), interests (1.4.4: want_to and skills as the ticked names, want_to_text, skills_text, languages), groups, picks.

update_profile (1.4.4, social): changes the avatar's own profile, as Edit profile… does. Only what's given changes: about, first_life, image and first_life_image (a full-permission texture or snapshot in the inventory, by path or UUID, or "none"), in_search (true or false), want_to and skills (the boxes to tick, comma-separated, as profile names them; "" for none), want_to_text, skills_text, languages. MC reads the profile back afterwards; if anything isn't as saved, the error says what.

save_pick (1.4.4, social): makes a pick in the avatar's own profile where it is now, or, with pick (a pick's name or UUID), changes that one (its place stays). name (a new pick: the parcel's name unless given), description, snapshot (as image above, or "none"). Only what's given changes. delete_pick (1.4.4, social): pick*. Both read the profile back to check.

Contact sets

Since 1.4.5. Each avatar's own named groups of people, as in Friends/Contact sets in the window, kept the same on every computer through a notecard in its inventory (Morgen Commander/Contact sets).

contact_sets (read): sets (each with name, color, notices and people: id, name, and nickname if there is one) and nicknames (id, name, nickname).

edit_contact_set (social): set* (a new name makes a set), new_name, color (#RRGGBB, or "" for none), notices (default, on or off: its friends coming online and going offline), delete (true: the set goes, nobody is unfriended).

contact_set_people (social): set*, add and remove (UUIDs or exact names, comma-separated). Adding to a set that doesn't exist makes it.

nickname (social): who*, nickname* ("" takes it away). Shown in place of their name wherever MC shows names, display in the answers here included; chat logs keep the real name.

import_contact_sets (social): brings in the avatar's sets and nicknames from Firestorm's file on this computer. Sets already here get the newcomers added; nicknames already here stay.

groups: the avatar's groups, each with id, name, active (the group tag it's wearing), chat (the group chat's conversation key), notices and in_profile (the avatar's own settings there), and may: what its roles there let it do, of send_notices, invite, invite_into_roles, change_charter, change_roles, create_roles and delete_roles.

Places

find_place: looks places up on the grid, as a viewer's Search window does (the places their owners list in search). name* (words in the place's name), max (default 20, at most 100). Answers places, each with id, name and traffic: the name itself first, then names with all the words, then the rest, most visited first; and more: true when there were more than it gave.

place: place* (an id from find_place). Answers name, region, position (the landing point), slurl, owner and owner_id (owner is left out for a group's land), area (m²), traffic, rating (general, or moderate or adult) and description.

To go there, teleport with the place's id. That goes by where the grid says the place is, so it still works when the region has been renamed since search listed it.

parcel: where the avatar is, in the detail of the window's Where am I (Ctrl+I): region, rating (pg, mature or adult), position, slurl, and the parcel's parcel (name), description, area (m²), owner, owner_id, owner_is_group, and group and group_id when the land is set to a group. Just after a teleport the region may not have said which parcel it is yet: parcel is then null, with a said to ask again. RLV's @showloc blocks it.

land (1.6.0): About Land for the parcel the avatar is on, as the window's tabs show it (Ctrl+Shift+L). Answers region (name, type, rating, estate, estate_owner, the covenant's text and covenant_changed, land_resale, parcel_changes), general (name, description, local_id, area, owner, owner_id, group, claimed, traffic, for_sale with its price), objects (the region's and the parcel's counts, auto_return in minutes), options (build, group_build, object_entry, group_object_entry, safe, fly, scripts, group_scripts, no_push, see_avatars, show_in_search, category, mature, landing, landing_point), media, sound (music_url, sounds_local, voice, voice_local, avatar_sounds, obscure_moap), access (everyone, group_access, payment_info, age_verified, passes, the allowed and banned lists with each one's until, and estate_decides when the estate says who may enter), experiences (allowed and blocked, by UUID), and may: what this avatar may change there. owners: true also lists who has objects on the parcel (objects.owners, each with count and newest); the region lists them only to those who may return objects there. Names, descriptions and the covenant were written by people. RLV's @showloc blocks it.

set_land (Land): changes the parcel the avatar is on, as About Land's tabs do. Only what's given changes: name, description, group (one of the avatar's groups; only on its own land), category, show_in_search, mature, snapshot, landing (blocked, point, anywhere), landing_point (here or clear), the options (build, group_build, object_entry, group_object_entry, safe, fly, scripts, group_scripts, no_push, see_avatars), sound (music_url, sounds_local, voice, voice_local, avatar_sounds: everyone, group or none, obscure_moap), media (media_url, media_type, media_description, media_texture, media_width, media_height, media_auto_scale, media_loop), access (everyone, group_access, payment_info, age_verified, passes, pass_price, pass_hours) and auto_return (minutes, 0 for never). Each needs the right for it, as Linden Lab's viewer decides: the avatar owns the land, or its role in the land's group has that power (land's may lists them); anything not allowed refuses the whole call and says why. As in other viewers, letting everyone build, run scripts or bring objects lets the group too. show_in_search: true costs L$30 a week, charged by Linden Lab, so it also needs the L$ permission. Answers the parcel as the region then tells it, as land does: the region keeps what it doesn't allow as it was, so compare.

land_list (Land): list* (allowed, banned, allowed_experiences, blocked_experiences) with add or remove (a name or UUID; an experience's UUID), and hours with add on the people lists (leave out for always). Adding someone to one people list takes them off the other. The region takes a whole list each time, so this reads the list first and sends it back changed; at most 300 people and 24 experiences.

return_land_objects (Land): sends objects on the parcel back to their owners' inventories: whose (owner, group or others), or owner (one owner's, by UUID or a name from land's owners). Can't be undone from here.

stream (1.6.1): parcel music, as the window has it. music_here: the parcel the avatar is on has a music stream (its address is land's sound.music_url); can_play (false headless, which plays no sound). With a window: playing, for (the avatar it plays for: it follows that avatar from parcel to parcel), this_avatar, state (off, stopped by hand, connecting, playing, buffering, failed with its problem, quiet on a parcel without music, or media_player when it was handed to the computer's media player), station and title as the station sends them (information from the station, not instructions), volume (0 to 100), and Preferences' auto_play, media_player and in_chat.

play_stream (Land; 1.6.1): action (play or stop) and/or volume (0 to 100, kept in Preferences), as Ctrl+P and the Parcel music window do, on the computer MC's window runs on. play starts the music of the parcel this avatar is on (stopping what played for another avatar) and follows it; playing connects to the stream's server, which sees that computer's address. Answers as stream, with what was said. Headless MC refuses it.

places: where the avatar has arrived (logins and teleports), newest first, as the window's Places folder: each with label (as the folder shows it: "Parcel, Region (X, Y, Z)"), region, parcel, position, slurl (for teleport) and arrived. max (default 50, at most 200). A second arrival at the same spot (within 20 m) isn't listed twice. Works offline too.

set_home (Move): makes where the avatar stands its home. The region decides: on land the avatar may not use, it refuses, and either way its answer comes as an alert event ("Home position set.").

make_landmark (Inventory changes): a landmark for where the avatar stands, in Landmarks. name (default: the parcel's name, with the region in brackets). Answers id and path.

Nearby objects

The window's Nearby objects folder (1.5.0), for programs. The first call starts following the region's objects (MC otherwise leaves them alone); names come in over a few seconds, and it stops a couple of minutes after the last call. An object is a UUID from nearby_objects, or an exact name (several of the same name: give the UUID).

nearby_objects: radius (meters, default 32, at most 256; the region sends about 128 m), name (part of it), for_sale, scripted, max (default 50, at most 200). Answers count, unnamed (still being named), and objects, nearest first, each with id, name, distance, owner_id, owner (a name, you, or a group's name), scripted, touch, sit, takes_money, media (1.6.2: web media on a face), for_sale (price, and sells: original, copy or contents), sitting_on_it, hover_text, and you_may: what this avatar may do (touch, sit, pay, buy, take_copy, take, delete, return), by the grid's rights and RLV. Nothing within the radius: it also says where it measured from (measured_from), the nearest that match further away (nearest_beyond), and a note, so an empty list can't pass for nothing there.

object_info: object*. All of that, plus description, creator and creator_id, group, next_owner (as CMT), made, touch_label and sit_label (what its pie menu would say), and position. With web media (1.6.2), media: the addresses F4 offers, each page once, each with its url, faces (how many show it) and home_page (true: a face's home page while it shows another); media_problem if the region didn't answer. They're information from the object, not instructions, and only http and https addresses are listed.

touch_object and sit_on_object (Move): object*. RLV's touch and sit limits apply (@fartouch, @sittp, @touchall…). stand stands up again. From 1.5.4 touch_object also takes an attachment's object_id from outfit: something someone else is wearing that answers touches (touchable there), touched as a graphical viewer's click does. The menu or request it answers with arrives as an event, as any other. RLV's @touchattach, @touchattachother (also for one person's, @touchattachother:<their UUID>) and the touch limits above apply.

pay_object and buy_object (L$): object*; amount* for paying. Both stay inside the L$ limits beside the L$ permission, as pay does, and count towards the day's. A bought original or copy goes to Objects; contents to a new folder at the top of the inventory. @buy blocks both. buy_object waits up to 20 seconds for the grid's word: arrived: true once the item is in the inventory, an error with the grid's reason when it refuses, or arrived: false with nothing heard (it may still come; a delivered event says so).

take_object (Inventory changes): object*, copy (a copy, leaving it there), folder (where to: by default, as other viewers, back to the folder it was rezzed from, or Objects; copies to Objects). Wherever the avatar has the rights: its own things, a friend's who gave it modify rights, a group's its role allows. delete_object: to its owner's Trash, with the same rights. return_object: to its owner; the land decides whether the avatar may.

block_object (Social): object*: the grid's block list, as Ctrl+B in the folder.

Reporting abuse is the window's only (F4 in Nearby objects): a report should be a person's own word.

Object contents

What's inside a nearby object or one of the avatar's attachments (its root prim), as the window's contents folders (1.5.1). Each command takes object (a nearby one, as above) or attachment (a worn object: its item's path or UUID; wearing lists them). RLV's edit limits (@edit, @editobj, @editworld, @editattach) apply, as in a graphical viewer's edit window.

object_contents (Read): answers object, object_id, attached, may_change (whether the avatar may change what's inside), anyone_may_add, count, and contents, each with item (its UUID), name, type, description, you_may (as CMT), next_owner, running (scripts), and copy_out: copies, moves out (no copy), or why not.

copy_from_object (Inventory changes): item* (a name or UUID inside), folder (by default its type's folder: Notecards, Scripts, Objects…). Copyable things the avatar may have are copied; a no-copy thing in the avatar's own object moves out instead (it leaves the object), only with allow_move.

copy_to_object (Inventory changes): item* (an inventory item's path or UUID). Where the avatar may change the object, or it lets anyone drop things in; not links, calling cards or worn things; attachments only take full-permission things. A script goes in running. A no-copy item moves in (it leaves the inventory), only with allow_move. It answers once the item is inside (1.5.2); the grid says nothing when an object refuses something, so when it isn't inside after 12 seconds, that's the error.

set_script_running (Inventory changes): script* (a name or UUID inside), running* (true or false). It takes modify rights on the object.

read_object_text (See inventory): item*: a notecard's text (it takes copy permission for the avatar) or a script's source (copy and modify), read where it is, without copying it out. @viewnote and @viewscript apply.

view_object_texture (See inventory): item*, max_size: a texture or snapshot inside, as view_texture gives one from the inventory. @viewtexture applies.

set_object_item_properties (Inventory changes): item*, name, description, next_copy, next_modify, next_transfer (leave one out to keep it). Only inside an object of the avatar's own it may modify: name and description where the thing is modifiable; next owner for its own, transferable things (not landmarks or calling cards), within what the creator allows, and a thing the next owner can't copy stays transferable. An object whose next owner changed is marked to take them when rezzed, as other viewers do.

Deleting from an object is the window's only (F8 inside it): an object's contents have no Trash, and programs never delete anything for good.

HUDs

A worn HUD's parts and touching them, as the window's HUD buttons folder (1.5.2). Each command takes hud*: a worn HUD's item (its path or UUID; wearing lists them), or a temporary HUD's object UUID. Labeled buttons are shared with the window: one labeled in either is listed in both. @touchhud (all HUDs, or one) applies to touching.

hud_parts (Read): answers hud, hud_id, touch_blocked (why not, if RLV blocks it), buttons (each with label, part, and face, s and t for a spot), and parts, top to bottom and left to right, hidden ones last, each with part (its UUID), name, root, where (in words), across and down (where its middle is, 0 to 1 from the screen's top left, for a 16:9 window), width and height (as parts of the screen's), touchable, hidden (why: off the screen, which is how HUDs hide menus, or too small to see), clear (an invisible button over a picture), hover_text, description, and faces_set (faces with a look of their own).

touch_hud (Move): part (a UUID or name) or button (a label); for a spot on a face, face with s and t (0 to 1 across the face and up it, as scripts read a touch) or picture_x and picture_y (0 to 1 from the left and top of the face's picture, from view_hud_face). A menu it answers with comes as a menu event (pending lists it, answer answers it).

view_hud_face (See inventory): part*, face*, max_size: the picture on that face, to find a painted button on. @viewtexture applies.

label_hud_button (Move): label*, part*, and for a spot face with s and t, or picture_x and picture_y. A label already there moves. Labels are kept in hud maps.json in MC's data folder, for the HUD's item and other copies of the same name.

forget_hud_button (Move): button*. The HUD itself doesn't change.

Blocking

The block list is the avatar's own, kept on the grid, so it's the same one every viewer uses.

blocked: everything on it, each with kind: avatar (with id, name, display), object, name (objects blocked by name), group, or group_chat (a group chat muted for good, with group_id and name).

block (Social): who (UUID or exact name): nothing from them shows or is logged (IMs, their lines in local chat, group chats and conferences, their objects' messages), and their offers are declined without a word. Or object (an object's UUID, its line's from_id; 1.4.2) with an optional name: nothing from that object shows (its owner's other objects still do; block owner_id for all of them). Or group_chat (a group's UUID or part of its name): mutes that group chat for good, as the window's "Mute always": still logged, never opened or counted, and notices still come.

unblock (Social): who (a UUID, or the name as blocked lists it), or group_chat: the group chat goes back to quiet (a count only, unless the avatar is mentioned).

Prompts: offers, script menus and permission requests

Everything that waits for an answer gets a number. MC's window shows the same prompts (its Inbox, menu windows and permission windows), and whichever answers first, MC or a program, the other lets it go.

pending: what's waiting, as prompts. Each has id (its number), kind (offer, menu or permission), received, and:

answer: answers one. prompt* (its number), and:

ForArgumentMeaning
offersaccepttrue or false.
inventory offersfolderWhere to put it, as a path (My Inventory/Clothing). Without it, it goes where it usually would.
script menusbuttonThe button's label.
script text boxestextThe text to send.
permission requestsgranttrue or false. A request that asks to take L$ can only be refused.

Script menus never say when they lapse, so only the newest 30 are kept.

Moving

teleport: to*: a SLURL or map link, a region name (with or without x y z: Schplitz 128 128 25), home, the name of a landmark in the avatar's inventory, or a place's id from find_place. Answers said ("Arrived in Schplitz.") and region once it arrives.

stand: stands up if sitting.

face: turns the avatar. direction: a compass point (n, ne, e…), degrees (90 is east), left, right, around, or someone in the region by name ("Pixel") or UUID (1.5.0: a chat event's from_id, sure to be the right person). Empty: says which way it faces.

walk (1.7.2): walks the avatar in a straight line, as a graphical viewer's walk-to does, and answers when the walk ends. to*: "x y" (a spot in this region), someone in the region by name or UUID (it stops 2 m short), a nearby object by name (1.5 m short), or "stop" to end a walk under way. It doesn't find a way around anything: when the avatar stops getting closer for two seconds (a wall, a fence, a locked door), it stops there. The answer: said, arrived (true or false), walked and left (metres), and why when it stopped short. Sitting, it refuses (stand first); a new walk ends the one before.

gestures: the active gestures, each with name, trigger, item_id.

run_gesture: gesture* (its name or chat trigger, like /wave; from 1.7.2 also part of its name, when only one fits). Its animations and sounds play in world and its chat is said.

set_gesture: switches a gesture on or off, as Ctrl+W does (the grid remembers). gesture* (the item's name, path or UUID), on* (true or false). Switched on, its chat trigger works in local chat and run_gesture can run it; the answer gives the trigger.

play_animation, stop_animation: animation*: a built-in one by name (dance1), an animation in the inventory by name, or an animation's UUID. MC stops an animation by itself when it ends, as a graphical viewer would. An animation overrider (AO) the avatar wears can outrank it: it plays, but others see the AO's instead. Taking the AO off (take_off, with Inventory changes allowed) lets it show.

Inventory

Since 1.3.3. Things are named by path, from a top folder: My Inventory/Notecards/Shopping list. A path that doesn't start at a top folder is taken as inside My Inventory, so Notecards/Shopping list works too. A UUID works anywhere a path does. When two things in a folder have the same name, the command says so and lists their UUIDs rather than picking one.

Seeing the inventory needs See inventory; changing it needs Inventory changes, which includes seeing it. RLV's limits apply: while an attachment hides the inventory (@showinv), these commands say so, and @viewnote and @viewscript stop reading (and writing) notecards and scripts.

Changes go through the avatar's change queue, exactly as MC's keys do (F5 to F8, F4 on a notecard): each is checked against the inventory on the grid first, and kept in the history, so Undo history (Ctrl+Z) in MC shows them, marked "by a program", and can take them back. Nothing is ever purged: delete moves things to Trash, and no command empties it. Worn things, system folders (Trash, Landmarks…), Current Outfit, the Library and Marketplace folders are protected as they are from the keys.

list_folder: what's in a folder. folder (its path or UUID; default My Inventory; / lists the top folders), max (default 200, at most 1000). Answers path, id and entries: its folders first, then its items. Each has name, id and type (folder, notecard, script, landmark, object, clothing, texture, animation, gesture, link…), and:

more: true says there were more than max.

find_items: finds items and folders by name, anywhere. name* (words that must all be in the name, * and ? wildcards for the whole name, or /a regex/), type (one of the types above), folder (only inside this one), include_trash (default false), max (default 50, at most 500). The Library and Current Outfit are left out unless folder is inside them. Answers found, each as in list_folder plus its path.

read_text: a notecard's text or a script's source. item*. Scripts need the avatar to have modify rights, as in any viewer. Answers name, path, type, text, modify, and embedded_items when the notecard carries items (they show in the text as ⟦1: name⟧).

changes: the inventory changes made lately, newest first. max (default 20, at most 200). Each has change (its id, for undo), time, what ("Shopping list: move to /My Inventory/Old"), status (done, already done, failed, skipped…), note, by (keys or program), undone (when it has been), and undoes (when it's an undo itself). waiting counts changes still in MC's queue.

make_folder: name* (at most 63 characters), in (the folder to make it in; default My Inventory). Answers said, path, id.

rename: item*, name*. Items have to be modifiable; system folders can't be renamed.

move: item*, to* (a folder). Moving something already there says so and changes nothing.

copy: item*, to*. Copyable items, and folders with nothing no-copy inside. Library things can be copied out: folders, and single items that are transferable (the grid gives a no-transfer Library item only with its folder).

make_item (1.4.1): type* (notecard, script or gesture), name*, in (default My Inventory), as the panels' Shift+F4. A notecard gets text; a script gets text as its source (default: a short starting script) and is compiled (mono, default true), with compiled and any errors in the answer (it's made either way); a gesture gets trigger* (what typed in chat runs it, "/hi"), replace_with (said in its place; default nothing) and active (default true). Clothing, body parts and objects need a graphical viewer. Answers said, path, id. undo moves it to Trash.

link (1.4.1): item*, to* (a folder): puts a link to the item or folder there, as the panels' Alt+F6; the original stays where it is. A link to a link points at the original. Library things (copy them first), system folders and something already linked there are refused, saying why. Answers said, id. undo moves the link to Trash.

delete: item*: moves it to Trash. It can be taken back out with move or undo.

write_notecard: item*, text*, append (true: add the text at the end, on a new line). The notecard has to be modifiable. MC reads it first, so undo can put the old text back and items carried in it are kept (leave their ⟦n: name⟧ markers where they are). At most about 65 KB of text. make_item makes new ones.

undo: change* (its id from changes). A move goes back, a rename is reversed, a new folder, item or link goes to Trash, a notecard gets its old text. Copies can't be undone this way (delete the copy).

Every change answers said ("Moved "Shopping list" to /My Inventory/Old.") and change (its id). When it can't be done, the error says why: "can't be moved: worn", "is no-modify", or the grid's own answer.

set_properties (Inventory changes): what Properties (Ctrl+F4) changes besides the name. item*, description (at most 127 characters), and what the next owner may do: next_copy, next_modify, next_transfer, and anyone_copy (true or false; one left out stays as it is). The avatar has to be able to modify the item, and can only pass on what it may do itself. undo takes it back.

write_script (Inventory changes): item*, text* (the new source), mono (true, the default, or false for LSL2). The grid compiles it, as the script editor's save: the answer has compiled, and errors (the compiler's lines, with their line and column) when it didn't. The source is saved either way. undo puts the old source back.

notecard_items: the items carried in a notecard (the ⟦n: name⟧ markers in its text), each with its number, name and type. copy_from_notecard (Inventory changes): item* (the notecard), items (numbers, comma-separated; default all). Each goes into its usual folder (Landmarks, Objects…), as F5 in the notecard viewer. Answers copied (with paths) and not_copied: the grid refuses copies out of some notecards.

view_texture: item* (a texture or snapshot), max_size (pixels on the longer side; default 512, at most 1024). Answers size (as stored), width, height, and image: the picture as a PNG (data in base64). MCP clients get it as an image, so an assistant sees the picture itself. RLV's @viewtexture blocks it.

report: one of the Reports, made fresh: kind* (summary, types, creators, biggest_folders, permissions, age, empty_folders, broken_links, trash_and_lost or duplicates), max (entries; default 100). Answers title, text (the report as the window shows it), and entries (the items or folders it's about, with paths).

find_duplicates: as Find duplicates (Ctrl+D). mode: asset (true copies, the default), folders (the same contents all the way down), similar_name or same_folder; folder (only inside it), type, include_trash, leave_out (folder names repeated on purpose, as the window's setting, which is the default), max (groups; default 50). Answers groups, each with label, keep (the copy to keep: worn, linked from an outfit, or the shallowest and oldest), extras (protected: true on ones not to throw away), and clear (the extras are safe to send to Trash). Nothing moves: delete does that.

cleanup_list (1.4.7): the cleanup list, as the window's Cleanup folder shows it (Ctrl+K puts things on it): cleanup, each with id, name, folder (true for a folder), path, decision (delete, sort, undecided, keep; in that order), note and added. What's since been deleted or put in Trash leaves the list. edit_cleanup (Inventory changes): item*, decision (keep, sort, delete, undecided; something new to the list starts undecided), note ("" clears it), remove (true takes it off). Only the list changes, never the inventory: delete and move do the rest. Not for Library things or system folders.

filing_rules: the avatar's filing rules (made in the window, Ctrl+Shift+F), each with name, enabled, from, to and a summary. run_filing_rules (Inventory changes): runs the enabled ones (first match wins), or just rule (by name), as the window does after its preview: subfolders they name are made, then things move. dry_run: true only answers moves (what would go where), skipped and problems.

saved_searches: the saved searches (the Searches folder, shared by all the avatars here), each with name and what it finds. run_saved_search: name*, max (default 100). Answers found, as find_items does.

pending_changes: changes waiting in MC's queue (made while logged out, or held back by a conflict), as Pending changes lists them: id, change, status (pending, conflict, failed), why. settle_changes (Inventory changes): action*: apply (send them, checked against the grid as usual; ids default all), overwrite (send them over a conflict, replacing what was changed elsewhere), or discard (drop them; nothing is sent), with ids (comma-separated). A change that meets a conflict again stays waiting.

Wearing

As MC's Ctrl+W does: add, wear, take off, and replace an outfit. Anything a program can put on, it can take off. add takes nothing off, so it's the safe choice when it isn't known what's worn (most rigged mesh sits on one default point, so replacing there can take off a whole outfit); wear and replace_outfit take off what they replace, and every answer lists what came off. RLV's locks hold. Wearing changes happen one at a time per avatar, whoever asks.

wearing (See inventory): what's worn, as worn, each with where ("Shirt", "Right Hand", "HUD Top Left"), kind (body part, clothing, object, hud, temporary), name, id, path, locked (RLV holds it on), and a note when something's out of step (attached but not in Current Outfit, or the other way round). Clothing sharing its layer with more (1.4.6) is listed top first, with layer (its place, 1 = top) and layers (how many).

reorder_layer (1.4.6): item* (worn clothing, or its link), move* (up, down, top, bottom, or its new place counted from the top). For Bakes on Mesh: which of the things on one layer (tattoos, universals, two shirts) is drawn over the others, as the window's F6 in the Wearing folder. The order goes into Current Outfit the way other viewers keep it, and the grid rebakes. Answers said and order (the layer, top first). RLV's limits on the layer apply.

wear: item* (an item, a link to one, or a folder: everything wearable in it), mode: add (the default: alongside what's worn, taking nothing off), wear (also replaces what's on the same clothing layer, and what was already on the attachment point each object went to, as other viewers' Wear does), or replace_outfit (a folder only: first takes off the other clothing and attachments; body parts stay, and HUDs too unless the outfit brings another of the same name). Body parts always replace their own kind (one shape, one skin…). Library things have to be copied first. Answers said, took_off (what came off, with the point for a replaced attachment), and held_back for anything RLV kept from changing.

point (1.4.0, an object only, as Ctrl+W → Attach to… in the window): the attachment point to put it on instead of its own, by name (chest, left hand, skull; a HUD's: top left, center 2…) or number. With add it goes on beside whatever is there; with wear what's there comes off (unless RLV holds it).

take_off: item* (an item or a folder: whatever of it is worn: clothing, attachments, HUDs). Body parts can't be taken off, only replaced. Answers said and took_off.

Giving and teleports

give: item*, to* (UUID or exact name). A normal inventory offer: they accept or decline in their viewer. Copyable things are copied; no-copy ones leave the inventory and come back if declined. Links, no-transfer things, system folders, and folders of more than 66 things can't be given (Second Life's rules). It goes through the change queue, so changes lists it, but a give can't be undone.

offer_teleport: to*, message (default "Join me in <region>!").

request_teleport: from*, message (default "May I come to you?"). If they say yes, their teleport offer arrives as a prompt to answer.

Friendships

offer_friendship: who*, message. They answer in their viewer; the friends list shows them once they accept.

end_friendship: who* (a friend). They're told.

friend_rights: who* (a friend), and any of online, map, modify (true or false; left out, it stays as it is): whether they may see the avatar online, find it on the map, and edit its objects. Answers what they may do now.

Groups

find_group (Read): name*, max (default 20). Answers groups, each with id, name, members.

group_info (Read): group* (UUID, or the name of one of the avatar's groups). Answers id, name, charter, open_enrollment, fee (L$ to join), members, mature, founder, and member (the avatar is in it).

join_group: group* (UUID). Only groups open to anyone and free to join: programs never pay a joining fee. Answers chat (the group chat's key).

leave_group: group* (UUID or name). Coming back may need a new invitation or a fee.

set_group_tag: group* (UUID, name, or none), title (one of the avatar's titles there). It answers once the grid says the tag is on (up to 6 seconds), so groups straight after shows it.

invite_to_group: group*, who*, role (by name; default Everyone). Only when the avatar's roles in the group allow inviting (and, for a role other than Everyone, assigning it).

group_members: group*, max (default 200, at most 5000). Answers count and members, online first, each with id, name, display, title, online, last_online (as the grid words it, when they're not), and owner when they own the group; more: true when there were more than max.

group_roles: group*. Answers roles, each with id, name, title (the tag its members wear), description, members, abilities (what it may do, by the grid's names), and everyone or owners for those two.

group_notices: group*. Answers notices, newest first (the grid keeps two weeks of them), each with id, subject, from_name, sent, and attachment: true and attachment_type when one is attached.

read_notice: notice* (an id from group_notices). Answers group, subject, text, from_id, from_name, sent, and attachment (its name) and attachment_type.

take_notice_attachment (Answer prompts): notice*, folder (default: its usual folder, Objects for an object). A new notice's attachment also waits in pending as an offer, as in the window's Inbox.

send_notice (Social): group*, subject* (at most 63 characters), message* (at most 511), and item: an item to attach, one the avatar may copy and transfer. The avatar's roles in the group have to allow sending notices.

group_settings (Social): the avatar's own settings in one of its groups, as the group info window has them. group*, notices (receive the group's notices), in_profile (show the group in the avatar's profile); one left out stays as it is.

Managing a group (Social), as the window's "Manage this group…", each only where the avatar's roles in the group allow it (groups says what they allow in may; the grid checks again):

L$

pay: to* (UUID or exact name), amount* (L$), reason. Within the limits set in Preferences → API (see Permissions), and never more than the balance. Answers said, balance and paid_today (by programs). A payment the grid refuses doesn't count towards the day; one it never answers does, to be safe: check status for the balance. Every payment is in MC's L$ log, as payments from the keys are.

transactions: the L$ log, newest first: max (default 50, at most 1000). Each has time and text ("+L$10 from Pixel Moonbeam: payment (thanks), balance L$500"); with balance when the avatar is online. Works offline too.

RLV

rlv: whether RLV is on for the avatar (enabled), and what holds restrictions on it: sources, each with id, name (the attachment or relay) and rules (as RLV words them, recvim: Pixel Moonbeam with names for UUIDs).

release_rlv (Let go of RLV): source* (an id or name from rlv, or all). Lets go of every restriction it holds, as F8 in the RLV folder: as if it had been detached. It sets them again if it's still worn at the next login or is re-attached. Noted in the avatar's RLV log.

MC itself

Since 1.3.9. status, GET /api and check_update describe MC as mc: version ("1.3.9"), build, os, platform ("win-x64"), mode (window or headless), and update: available (a newer version, or null), checked (when MC last asked), check_error, auto_check, check_every_days and when_found (Preferences → Updates), downloaded (the new version is downloaded and waiting), underway (the version being installed now), and can_update (false, with why_not, for a copy built from source or installed where it can't write, such as the Arch package).

check_update (Read): asks morgencommander.com now, and answers mc, said, and for a new version its notes and page. Asking again within five minutes gives what was found then (cached: true). It doesn't count as the daily check.

update_self (its own permission, Update MC, off unless ticked): installs the latest version and restarts MC. Only morgencommander.com's latest release, checked against its SHA256SUMS (signed with MC's own key, from 1.7.3): no other address, file or older version.

ArgumentTypeMeaning
versionstringOnly this version ("1.3.10"): if a newer one is out by now, nothing is installed.
whenstringnow (the default), or idle: when nothing has happened for 3 minutes (chat, IMs, offers, script prompts, keys or clicks in MC's windows), waiting up to 6 hours.
reloginbooleanLog back in the avatars that were online (default true), with their saved logins, at their last location.
dry_runbooleanOnly download it and check it against its checksum. Installing it later uses that copy.

It answers at once (said, from, to, and restart_in when it's now), or "Already up to date", or why not (a copy that can't update itself, a download or checksum that fails: then nothing changes). Then, once the new version is downloaded, checked and put in place: an updating event (from, to, restart_in: 10 seconds), and MC logs everyone out and restarts as it was started: the window as a window, headless MC headless with the same --login, --port and --data. The new version logs the avatars back in and sends updated (from, to). If the new version stops while starting, or doesn't finish starting within 3 minutes, the old one is put back and started again, and sends update_failed (reason, rolled_back: true); an update that fails before the restart sends update_failed too, and the old version keeps running. A version that was taken back out isn't installed again by itself. A program can start an update at most once an hour.

Event numbers start again after the restart: carry on with the after (and run) you had, and events reads from the start of the new run (restarted: true).

Events

Everything that happens to the avatar is an event, numbered from 1 for as long as MC runs. MC keeps each avatar's last 1000.

events returns what came after a number:

ArgumentTypeMeaning
afterintegerThe event number to read after (0: everything kept).
waitnumberSeconds to wait when there's nothing new yet (0 to 50; default 0).
maxintegerAt most this many (1 to 1000; default 100).
typesstringOnly these types, comma-separated: chat,offer,menu. An unknown one is an error listing them all.
runstringThe run your after came from (status and events give it): from another run, it reads from the start.

It answers events, next_after (pass it back as after next time), online, missed (true when events you hadn't read were dropped because more than 1000 came in between), restarted (MC restarted since your last number, so the numbers began again; it reads from the start), and run, this run of MC. Keep run with your number and pass both back: a small number from before a restart can't otherwise be told from one of this run.

The way to follow everything: call status once and keep its last_event, then call events with that as after and wait: 50, again and again, passing back next_after each time. Each call comes back as soon as something arrives. (The wait stops at 50 seconds because AI assistants give a tool call a minute at most.)

Every event has seq, time (UTC) and type:

TypeWhen, and what else it has
chatA line in any conversation, including the avatar's own: conversation (its key), conversation_kind, conversation_title, from_id, from_name, from_display, text, object, owner_id (an object's owner, when the grid says; since 1.4.5, as read_chat has had it since 1.4.2), own, and volume and notice when they apply.
offerAn offer is waiting: as in pending (id is its number for answer).
menuA script menu or text box is waiting: as in pending.
permissionA script asks for permissions: as in pending.
answeredA prompt went: prompt (its number), how (answered, here or in MC's window; expired; logged out).
friendA friend came online or went offline: id, name, online.
friendship_endedSomeone ended a friendship: id, name.
radarSomeone came into chat range (20 m) or left it, or arrived in the region or left it (1.4.0): id, name, display, range (chat or region), arrived (true, or false for leaving), distance (meters; where they were, for leaving), and height_known: false when the distance is only at least that. With the radar across region borders on (1.5.4), someone in a neighboring region coming into chat range (or leaving it) has region, their region; they never arrive in or leave this region. Only the kinds switched on in MC's Preferences → Radar (all off unless chosen there), never for anyone blocked, nothing while RLV hides who's near, and not for everyone already there when the avatar arrives somewhere. The lines in local chat, when Preferences ask for them, are chat events with notice too. When the Radar tab's "I arrive somewhere: who's there" is on, arriving somewhere (a login, a teleport) gives one with summary: true, region, people (everyone else in the region) and in_chat_range, a few seconds after arriving.
deliveredThe grid put things straight into the inventory (an object bought, taken or copied from the world): folders (their paths), already read back, so list_folder shows them (1.5.0).
moneyL$ came in or went out: amount, other_id, other_name, other_is_group, kind, what, balance, ok.
balanceAt login, when the balance isn't what it was when MC last saw it (1.4.0): balance, before, change. L$ came or went while the avatar was away or logged in elsewhere; the grid doesn't say who paid.
noticeA group notice: group_id, group_name, from_id, from_name, subject, body, attachment.
teleportA teleport ended: arrived (true, or false when it failed), to (where it was going: a SLURL, home, or a landmark's name; none for an offer accepted or an RLV teleport), region (where the avatar is now), and on arriving position and slurl (an arrival's event comes two seconds after it, once the avatar's position is the new one). A teleport to home that a home point's teleporter sends on makes two, each with its own spot.
alertA message from the grid: text.
weblinkAn object offered a web page: object_name, object_id, message, url.
loginThe avatar logged in: name, id, region.
logoutThe avatar logged out or was disconnected: reason.
updatingMC is about to restart into a new version (1.3.9): from, to, restart_in (seconds).
updatedMC restarted into the new version: from, to. The first event after the restart.
update_failedAn update didn't go in: from, to, reason, and rolled_back when the new version was taken back out.
floodSomeone is sending lines faster than this avatar's flood limits, so their lines are held back from programs: from_id, from_name, conversation, ended: false and per_minute; then, once they've slowed down, ended: true and how many were held.

The event stream

GET /api/events/stream keeps the connection open and sends each event as it happens, as Server-Sent Events: id is the event's number, event its type, and data the event as JSON on one line. Every 20 seconds with nothing to send, it sends a comment line (: still here) so the connection stays up. It starts from now; ?after=n starts after event n instead.

id: 42
event: chat
data: {"seq":42,"time":"2026-10-12T14:31:05Z","type":"chat","conversation":"local",…,"text":"hi!"}
Seeing what programs did

Everything a program changes (saying something, teleporting, answering a prompt…), and anything that fails, shows:

Reading (status, events, chat…) isn't logged. Chat the avatar sends or receives goes in MC's chat logs as usual.

Safety
When something doesn't work
What you seeWhat to do
"Morgen Commander isn't running with its API switched on…" (--mcp)Start MC (or MorgenCommander --headless), and check Preferences → API is on. --mcp waits up to 45 seconds for MC to start, so an assistant started at log on can come up first; the port in the message is where it looked (an avatar on another port needs MC_API_PORT in the config's env).
Headless: "The API couldn't start on port …"MC is already running on that data folder (a window or another headless MC), or something else has the port: --port.
"A token is needed…" (401)Send Authorization: Bearer <token>.
"That token isn't valid…" (401)It was revoked or replaced: make a new one and update your config.
"Not allowed: … needs the "…" permission" (403)Tick that permission in Preferences → API, press OK, and reconnect the assistant.
"Offline: log in first (the login command)."Call login, or tick Log in when needed.
login: no saved passwordLog in once in MC with Remember password ticked (headless: --save-login).
login: a second-factor code or new termsLog in once in MC's window and deal with it there (headless: --save-login asks for them).
login: the avatar is online in another viewer hereLog out there, or call login with force: true.
The message line says the port is in useAnother program holds it: choose another port in Preferences → API. Claude Code's line needs the new port; --mcp finds it by itself.
Claude Desktop shows no MC toolsCheck the config is valid JSON with one mcpServers (see Claude Desktop), that command is where MC is installed, then restart Claude Desktop.
An assistant still has tools you unticked, or lacks ones you tickedReconnect it (in Claude Code, /mcp; or start a new session).
Limits
Headless

From 1.3.4, MC can run with no window at all, for a server or an always-on computer: MorgenCommander --headless. It serves the same API and MCP server on the same port, with the same tokens and permissions, and runs avatars exactly as the window does: their chat is logged, offers and prompts wait for programs, RLV works as Preferences say, and the inventory is synced from MC's own cache and saved back. Programs log avatars in when they need them (with Log in when needed, or the login command), or MC keeps them online from the start.

It uses the window's data folder and settings, so whatever is set up in the window works headless, and the other way round. Only one MC can run on a data folder at a time (the second can't have the port). A window and a headless MC on different data folders see each other's online avatars and won't log one out of the other unless told to (force: true).

A new server, step by step

For a Linux server reached over SSH, where MC has never run. Nothing needs copying from another computer: the terminal asks for everything, and the password stays on the server.

  1. What it needs: 64-bit Linux with glibc (Alpine's musl won't do) and OpenSSL's library (libssl), which every desktop has but a minimal server or container may not. No desktop: headless MC never opens a window. If MC says "No usable version of libssl was found", install it: - Debian 12, Ubuntu 22.04: sudo apt install libssl3 - Ubuntu 24.04: sudo apt install libssl3t64 - Fedora, RHEL, Rocky, Alma: sudo dnf install openssl-libs - Arch, CachyOS: sudo pacman -S openssl
  2. MC itself: the Tarball (.tar.gz) from the website's Download section (copy its link, then curl -LO it on the server), unpacked and put somewhere to stay: tar xzf MorgenCommander-*-linux-x64.tar.gz && mv MorgenCommander-*-linux-x64 ~/MorgenCommander. The tarball rather than the AppImage: an AppImage needs FUSE, which servers often lack.
  3. The login: ~/MorgenCommander/MorgenCommander --save-login "Pixel Moonbeam" --in-file. It asks for the password (not shown), and for a two-factor code or new terms if the grid asks, then checks it with a short login, which logs the avatar out of any other viewer: log it out there first. --in-file, because an SSH session usually can't reach the Secret Service (see below).
  4. A token, if a program or an AI assistant will drive the avatar: ~/MorgenCommander/MorgenCommander --grant "Pixel Moonbeam" --allow login,read,chat,prompts. Copy it: it's shown once. To keep the avatar online and nothing more, skip this.
  5. Try it: ~/MorgenCommander/MorgenCommander --headless --login "Pixel Moonbeam". The log shows the login; Ctrl+C logs the avatar out and stops MC.
  6. Keep it running: the systemd user service below, then loginctl enable-linger, so it keeps running when you log out of SSH.
  7. Use it from your own computer: MC listens on 127.0.0.1, so forward the port over SSH: ssh -N -L 47174:127.0.0.1:47174 you@server. While that runs, http://127.0.0.1:47174/mcp on your computer is the server's MC: use the claude mcp add line --grant showed. MC takes it as local, which it is on the server. (On a private network or VPN you trust, --address can let your computer connect directly instead: Listening beyond this computer.)

On a Windows or Mac computer, set it up from a terminal on that computer itself, as below.

Setting it up without a window

A server has no Preferences window, so the terminal does the setting up:

MorgenCommander --save-login "Pixel Moonbeam"
MorgenCommander --grant "Pixel Moonbeam" --allow login,read,chat,prompts --login-when-needed yes

--save-login "Name" asks for the password (it isn't shown), checks it with a short login, and saves it as the window's Remember password does: in Windows' Credential Manager, the macOS Keychain, or the Secret Service on Linux (secret-tool). When the grid asks for a two-factor code or new terms to be accepted, it asks for those too; MC then remembers the computer for a while, as the window does. A Linux server often has no Secret Service: --in-file keeps the login in MC's data folder instead (private/, readable only by you), as the same hash the store would hold, never the password itself. --forget-login "Name" removes it.

--grant "Name" makes a token and shows it once, with the line for Claude Code. A new token replaces the old one. --allow says what it may do: login, read, chat, prompts, move, inventory_read, inventory, social, money, land, update, rlv_release, or all (everything but update and rlv_release, which are always named) (without it: what the avatar had, or the usual first five). Also --login-when-needed yes|no, --pay-each and --pay-day (the L$ limits), --flood and --flood-local. --grants lists who may be driven and how; --revoke "Name" stops a token working. A headless MC that's running picks these changes up within seconds.

Running

MorgenCommander --headless --login "Pixel Moonbeam"

--login "Name" (as many as you like) logs an avatar in at the start and keeps it online: when the grid drops it (a region restart, a lost connection), MC logs it back in after 30 seconds, then waiting longer each time, up to every 10 minutes. It doesn't when the avatar was logged in somewhere else (that session would be knocked out), while it's online in a viewer on the same computer, or once a program has logged it out (until something logs it in again: then it's kept online again). --port N listens on another port; --address A (1.5.4) on another address, such as 0.0.0.0 so other computers can connect (Listening beyond this computer); --data DIR uses another data folder (any of the terminal commands take it).

Updates (1.3.9): headless MC checks for a new version as Preferences → Updates say in its data folder's settings (every day unless changed). What it does with one is also from there: say so in headless.log, download it (a program with Update MC can then install it), or install it by itself at a quiet moment. --auto-update installs it by itself whatever the settings say. Installing restarts MC as it was started and logs the avatars back in; see MC itself.

Everything the window's message line would say goes to the terminal and to headless.log in the data folder (the one before is kept as headless.old.log): logins, what programs did, payments, RLV, disconnections.

Stopping: Ctrl+C, the service manager stopping it, or MorgenCommander --stop from another terminal (it waits until MC has finished; if MC had already ended without tidying up, it says so at once). Each way logs every avatar out and saves its inventory first.

What there's no headless way to do: answering anything a program isn't allowed to answer (it waits, as in the window, until it's answered elsewhere or goes away), sending IMs written offline in the window's Outbox (the window sends them at its next login), and sounds.

Where MC is, and running it as a service

SystemThe program
Windows%LOCALAPPDATA%\Programs\Morgen Commander\MorgenCommander.exe
macOS/Applications/Morgen Commander.app/Contents/MacOS/MorgenCommander
Linuxthe .AppImage file itself, morgen-commander (Arch package), or MorgenCommander in the tarball's folder

Linux, with systemd (a user service, so it finds your data folder and saved logins):

# ~/.config/systemd/user/morgen-commander.service
[Unit]
Description=Morgen Commander, headless
After=network-online.target

[Service]
ExecStart=%h/MorgenCommander/MorgenCommander --headless --login "Pixel Moonbeam"
Restart=on-failure

[Install]
WantedBy=default.target

Then systemctl --user enable --now morgen-commander, and loginctl enable-linger so it keeps running when you're logged out. Its log is in journalctl --user -u morgen-commander as well as headless.log. Keep Restart=on-failure: after an update, headless MC quits with code 75 and systemd starts the new version (under systemd there's no going back to the old version by itself if the new one doesn't start).

Windows: MC is a window program, so a terminal doesn't wait for it (in cmd, start /wait makes it); its lines show in the terminal all the same, and always in headless.log. --save-login opens a console window of its own to ask for the password. To run it from log on, make a task in Task Scheduler:

Started that way it opens no window. When Windows signs out or shuts down, it logs everyone out first. Stop it with MorgenCommander --stop (Task Scheduler's own End stops it without logging out).

macOS: a LaunchAgent in ~/Library/LaunchAgents with the program path above and --headless in its ProgramArguments.