38 KiB
MCP server: RetroArch as a tool for AI assistants
RetroArch can act as a Model Context Protocol
server, so an AI assistant that speaks MCP can drive it: pause and resume,
load and save states, take screenshots, read core memory, load content.
Every tool is one of RetroArch's network commands, described as HELP
describes it on the network command interface. Not every command is a
tool: tools/list leaves out the ones an assistant has no use for, or
that another tool covers.
The server is off by default.
Turning it on
In Settings > Network, turn on MCP Server. Two more entries appear:
| Key | Default | Meaning |
|---|---|---|
mcp_server_enable |
false |
Runs the server. Takes effect when RetroArch next starts. |
mcp_server_port |
55357 |
TCP port. |
mcp_server_token |
The token every client must send. Made on the first start when empty. | |
mcp_server_bind_address |
127.0.0.1 |
Address to listen on; retroarch.cfg only. |
Restart RetroArch. The log reports the address:
[MCP] Listening on http://127.0.0.1:55357/mcp.
If it cannot listen there - another RetroArch still running holds the port, say - it says so on screen as well as in the log, since a client would otherwise be talking to that other RetroArch without knowing.
On the first start a random token is made and shown under MCP Server
Token. It is saved with the other passwords in the keychain, never in
retroarch.cfg. A build without the crypto library cannot make one:
enter your own there, or set mcp_server_token, before the server will
start.
Connecting a client
Clients that support MCP over HTTP ("Streamable HTTP") need three things:
- the address:
http://127.0.0.1:55357/mcp - the transport: HTTP
- a header:
Authorization: Bearer <token>
Where these go depends on the client. Many take a JSON entry of this shape in their MCP server configuration:
{
"retroarch": {
"type": "http",
"url": "http://127.0.0.1:55357/mcp",
"headers": { "Authorization": "Bearer <token>" }
}
}
The server speaks protocol revision 2026-07-28, and 2025-11-25, 2025-06-18
and 2025-03-26 for clients that open with initialize. Its list results
and server/discover carry ttlMs: 0 and cacheScope: "private", as
2026-07-28 requires
them: the tools are compiled in and listChanged is false, so nothing
would tell a client holding a list that an upgrade changed it. A client
that keeps one anyway sees a rebuilt RetroArch's new parameters once it
reconnects.
Over stdin and stdout
A client that starts RetroArch itself can talk to it on stdin and stdout instead of a port, with no token: only the process that started RetroArch holds the other ends.
{
"retroarch": {
"command": "/path/to/retroarch",
"args": ["--mcp-stdio"]
}
}
Each message is one line of JSON. stdout is kept for them; whatever
else would write there, RetroArch's own log and any core's included,
goes to stderr. The MCP Server setting does not need to be on for this.
Over stdin and stdout RetroArch also offers logging: after
logging/setLevel, what it logs at that level and above arrives as
notifications/message. When the client closes stdin, RetroArch quits.
The handshake
initialize answers with instructions: how the tools fit together to
play a game - find it with LIST_PLAYLISTS and GET_PLAYLIST, load it
paused, WATCH what each step needs, step with STEPS - queued, so
the game plays on while the next stretch is planned - PRESS ... until
or RUN_UNTIL, and STATE checkpoint before a risky move. A client
shows this to the model once rather than in every tool.
Every tool also has a title for people, made from its name: Run frames for RUN_FRAMES.
What the tools do
A tool is named as its command (GET_STATUS, STATE,
SCREENSHOT). Its parameters are named, typed and
marked needed or not, so a client is told what to send rather than
having to write the command's own line by hand:
{ "name": "LOAD_CONTENT",
"arguments": { "core": "/path/to/core.so", "content": "/games/a.rom" } }
STATE takes an action, and a slot number for save and load,
GET_PLAYLIST takes
playlist and an optional first, OPTION takes an action, an
option and a state of on or off - which the schema gives as the
only two values it accepts. tools/list describes every one of them.
A parameter that is needed and left out, one that should be an integer
and is not, one the tool does not take, a value outside the set a
parameter offers, one sent as true, false, null, an object or an
array - no tool takes those - and a tool that does not exist are
answered before
anything runs, as JSON-RPC invalid params (-32602) rather than as a
tool failure. The schemas leave other names unforbidden to keep the
tool list short; the server refuses them instead, so a misspelt
parameter is never dropped and the command run without it.
The single argument string this server took before the parameters
still works, so a client holding a cached tool list keeps going until it
reads the new one.
The tool's result is what the command answers; commands that answer
nothing report Done..
GET_STATUS and READ_CORE_MEMORY answer one line, and give it as
fields of its own: {"state": "PLAYING", "system": "nes", "content": "Super Mario Bros.nes"} and {"address": "1000", "bytes": "AA 0F 10"}. The last field takes the rest of the line, so a comma in a
game's name stays in it. A read that runs past the end of one region
goes on into the next; where nothing maps the rest it stops there and
says so, TRUNCATED 2 after the bytes, given as truncated: true, read: 2.
Results that are rows
The replies that are lines of tab-separated fields - OPTION,
LIST_CORES, LIST_PLAYLISTS, GET_PLAYLIST, CORE_OPTION,
GET_MEMORY_MAP, GET_LOG, INPUT, WATCH, RUN_FRAMES, PRESS,
RUN_UNTIL, STEPS and MENU - come
with structuredContent beside the text, so a client is handed the
rows rather than splitting them itself. Each of those tools declares an
outputSchema naming its columns, described by the first tool in the
list to answer with them - RUN_FRAMES for the watched bytes, which
PRESS, RUN_UNTIL, STEPS and WATCH then name without repeating:
{ "content": [ { "type": "text",
"text": "0\tSuper Mario World\t/games/smw.sfc\t/cores/snes9x.so\n" } ],
"structuredContent": { "rows": [ { "index": "0",
"label": "Super Mario World", "content": "/games/smw.sfc",
"core": "/cores/snes9x.so" } ] } }
The columns are option and value for the options, name and path
for the cores, playlist for the playlists, index, label, content
and core for a playlist's entries, key, value, description and
values for a core's options, start, length, select,
disconnect, kind, access, order and space for the memory map,
player, buttons and axes for what a player holds, and label,
address and value for the bytes WATCH watches, and index,
label and value for the menu's entries. Every field
is a string: it is the text's own field, which the server does not read
as anything else.
A tool answers with structuredContent exactly when it declared an
outputSchema and succeeded, so a client reads the schema it was
handed at tools/list and does not have to probe each reply. The
end-to-end test calls every tool that declares one and holds each reply
to it: the required fields, the declared types, and no field it leaves
out. A reply
marked isError is its reason as text, with no structuredContent. A tool with no
outputSchema answers with text alone, because its reply is prose or a
confirmation rather than rows.
A reply may end short of its columns, and the schema requires only the
ones every row carries: CORE_OPTION show gives an option's values
only where it was asked for that option by key.
A line the command opens with its own name, such as LIST_CORES none,
is not a row. Neither are the lines that carry a number about the reply
rather than a row of it, which become fields of their own - the number
ending the line, so PRESS 1 right+a 4 gives frames: 4:
| Line | Field | Where |
|---|---|---|
MORE |
more: true |
a list cut short with nowhere to resume |
MORE 200 |
more: true, next: 200 |
GET_PLAYLIST's next page |
NEXT 48 |
next: 48 |
where GET_LOG reached |
SKIPPED 12 |
skipped: 12 |
log lines gone before the first kept |
RUN_FRAMES 3 |
frames: 3 |
the frames RUN_FRAMES ran |
PRESS 1 a 4 |
frames: 4 |
the frames PRESS ran |
MET 12 |
met: 12 |
the frames RUN_UNTIL ran until the byte met it |
WAITING 540 |
waiting: 540 |
the frames it ran without that |
VALUE 5 |
value: 5 |
what RUN_UNTIL, or a PRESS with until, waited on holds |
QUEUED 4 |
queued: 4 |
the steps a queued STEPS has left to run |
DISCARDED 3 |
discarded: 3 |
the steps a queued STEPS dropped, as the queue had ended |
PREVIOUS STOPPED 43 STOP 1 STEP 1 |
previous: {"stopped": 43, "stop": 1, "step": 1} |
how a queued STEPS ended, on the next reply; PREVIOUS ERROR <why> gives error |
IDLE 1830 |
idle: 1830 |
milliseconds the content has sat paused since the queue ran dry |
DONE 30 |
done: 30 |
the frames STEPS ran when every step had |
STOPPED 12 |
stopped: 12 |
the frames it ran when its stop held |
STOP 2 |
stop: 2 |
which stop held, from 1, when STEPS stopped |
STEP 3 |
step: 3 |
the step it ended on, from 1 |
TRUNCATED 2 |
truncated: true, read: 2 |
a READ_CORE_MEMORY that met unmapped memory |
CLOSED |
closed: true |
MENU with the menu closed |
SELECTED 3 |
selected: 3 |
the menu entry selected |
COUNT 40 |
count: 40 |
the entries in the menu's list |
MESSAGE Press again to quit |
message: "Press again to quit" |
a message over the menu, on any line |
KEYBOARD Username |
keyboard: "Username" |
the menu asking for text, on any line |
PATH Main Menu > Settings |
path: "Main Menu > Settings" |
the lists above the menu's own, on any line |
MORE 50 |
more: true, next: 50 |
the menu's next page, as from takes it |
GET_LOG always says where to go on from, so it carries next without
carrying more: a client asks again from next and gets whatever has
been written since.
GET_LOG carries no rows: the log is its lines, and a page of them runs
to 60 kB, so answering with a row apiece would send the whole page
twice. Its structuredContent is the trailers alone - {"next": 482}
- and its
outputSchemadeclares only those.
The text is unchanged: a client that reads it and nothing else sees exactly what it always did. A game whose name holds a tab is the one thing it will read wrong, and the rows get right - the fields before and after the name are read from the ends of the line, so the stray tab stays inside the name.
Both come from revision 2025-06-18, which added them; a client of
2025-03-26 is sent neither. Over HTTP the revision is the one the
client names in MCP-Protocol-Version on each request; over stdin and
stdout it is the one agreed at initialize, and it holds for the
session.
Not every command is a tool. HELP and VERSION are not, because
tools/list already lists the commands and every answer names the
server's version, and neither are the toggle hotkeys or
GET_CONFIG_PARAM, whose work OPTION does below.
Nor is a hotkey that steps a selection. A person presses
STATE_SLOT_PLUS while watching the slot on screen; for a program the
command that takes the value outright is the tool, and stepping towards
it is only a way to get the value wrong: STATE save over
STATE_SLOT_PLUS and SAVE_STATE, REPLAY seek over
NEXT_REPLAY_CHECKPOINT, REPLAY play over PLAY_REPLAY. Where
nothing reports the selection either - which cheat is picked, which
shader preset is loaded - there is nothing worth offering yet, and a
tool that writes where it cannot read is worse than none.
READ_CORE_RAM and WRITE_CORE_RAM are not tools either: they take an
achievement address, which looks like READ_CORE_MEMORY's system
address and is not one, and GET_MEMORY_MAP answers the addresses
READ_CORE_MEMORY takes.
The disc is the exception: DISK steps blind, and a disc swap is part
of playing a game. It is one tool taking a choice - DISK next -
rather than a tool per hotkey; MENU, below, answers with where it
landed.
REINIT, STATE, REPLAY, CORE, INPUT, OPTION and
CORE_OPTION stand for their families likewise: STATE load 3 is
LOAD_STATE_SLOT 3, REPLAY seek 600 is SEEK_REPLAY 600, CORE load <path> is LOAD_CORE <path>, INPUT set 1 a 1 is SET_INPUT 1 a 1,
and OPTION show pause is GET_OPTION pause. A reply that is rows -
INPUT's, OPTION's - is the tool's answer as it is. Each
answers under its own name - STATE load 3,
DISK next pressed, REPLAY ERROR no replay is playing or recording,
and REINIT audio for a restart that says nothing itself - while the
commands sent by name answer as they always have. DISK is refused on
a core with no disk control, where the hotkeys would do nothing. A word
the tool does not take is invalid params naming the ones it does; on
the line interfaces it is STATE ERROR one of save|load|checkpoint|rollback, and so is
anything after a word that takes nothing. REPLAY's slot or frame is its number parameter.
SAVE_FILES and LOAD_FILES are not tools: the core writes its save
files itself, and playing a game does not need them.
All of them are still commands on the network and stdin interfaces, where a person is typing and can see what happened.
The menu
MENU <action> [index] [from <entry>] reads and drives RetroArch's own
menu - settings, playlists, cores, the Quick Menu - and answers with
what it shows once the action has run: its title, a page of 50 entries
holding the selection, which entry is selected and how many there are.
MENU down
MENU Quick Menu
0 Resume
1 Reset
2 Close Content
3 Save States ...
SELECTED 1
COUNT 15
The menu opens where it was left, so below the title PATH names the
lists above it - PATH Main Menu > Settings > Drivers - and b goes
back up them. Where the list runs past the page, MORE 50 says where
the next one starts, for from.
XMB and Ozone keep their top level in tabs - Main Menu, Settings,
History, the playlists - rather than in one list. On XMB, left and
right at the top switch tabs. On Ozone, left moves to the tabs,
up and down pick one, and right returns to its list; a there
only returns too. A playlist's tab is titled with the playlist's name.
Each entry is its index, its label and its value: a setting's value,
... for an entry that opens a list, or checked for the current
choice in a list of them - the driver in use, say. title, rows, selected
and count are its structured fields.
showanswers what the menu shows;fromlists from that entry.openandcloseopen and close it. With it closed,showandcloseanswerCLOSED, and the rest are refused. With no content running the menu cannot close, andclosesays so.select <index>moves straight to an entry, rather than pressingdown137 times.up,down,left,right,aandbpress the menu's buttons:leftandrightchange a value,aconfirms,bgoes back.left,rightandatake an index too, acting on that entry:MENU a 3opens Save States.type <text>answers a keyboard: one line, entered whole and confirmed, as a platform's own keyboard hands it over.
What waits on the user comes as a line of its own after the title. A
message - MESSAGE Press again to close content..., the confirmation
Close Content, Reset and Quit ask for - is confirmed with a and
dismissed with b. An entry that asks for text - a username, a search
- answers
KEYBOARD Username, andtypeorbends it.
The action runs on the menu's next frame as its own input would, and
the answer comes a frame after that, so a list or a message an action
opens is there to read. MENU open and close are the menu's switch:
menu is not an OPTION. A second MENU while one waits replaces it, answered
with an error; one whose list another hand changes first does nothing
to the entry that took its place, and says so; and one whose menu closes first - a hotkey, another
client - is answered CLOSED. MENU is marked destructive: its
entries include Quit, Close Content and Delete. It is RetroArch's menu, not a game's: a game's menus are
its screen and memory, played with PRESS, STEPS and WATCH.
Options
A hotkey toggle is of little use to an assistant: FAST_FORWARD turns
fast-forward on or off depending on what it already was, which cannot be
known without asking. OPTION replaces the toggles with something that
can be asked and told:
OPTION show [option]reports every option and its value, name and value tab separated, one per line; with a name, that option's line alone.OPTION set <option> on|offputs an option in a state. Asking for the state it is already in changes nothing and succeeds, so the same request twice is one change.
Each option is read where its state lives rather than from the setting
behind it, so OPTION show reports what is true now and not what was
configured. Which options a build has depends on what it was built with,
so OPTION show with no argument is the list: it covers what is on or off
(pausing, fast-forward, mute, the shader, recording), what the
frontend is doing (the frame count, the state and replay slots, whether
content is loading), and the configured directories. Some only report,
and OPTION set says so for them.
Options take effect at once and report the resulting state. Speed changes respect the runloop's pause, netplay, core override and hardcore restrictions. An option that cannot change right now is an error. Recording and streaming share one recorder; stop the active mode before starting the other.
A hotkey tool that is still a tool answers <NAME> pressed for the same
reason: the press goes out on the next poll, and what it
changed is read back with OPTION show.
GET_LOG [since] gives the lines RetroArch has logged since line
since (0 when left out), as far as the logging verbosity lets them be
logged, then NEXT and the line number to ask from next time; when
lines were overwritten before they were read it says SKIPPED and how
many first. The last 256 lines are kept, from when the MCP server
starts or the first GET_LOG.
PRESS <player> <control>[+<control>...] <frames> is how an assistant
taps a button: it holds the buttons, runs that many frames and lets
them go, answered once the last frame has run. A tap is 2 to 4 frames;
PRESS 1 right+a 6 runs and jumps. What INPUT set holds stays held,
under the press and after it: INPUT set 1 right+b 1 then PRESS 1 a 20 is a running jump.
This is one request where four were needed - INPUT set, RUN_FRAMES,
INPUT set to release, RUN_FRAMES again - and each of those is its
own HTTP connection, so it is latency saved as much as tokens. The
buttons are let go of however the press ends, including the error that
ends it early. Axes are INPUT set's: they are held at a value rather
than pressed, so PRESS refuses one.
PRESS ... until <condition> lets go and runs on until the condition
holds, as RUN_UNTIL would, and answers as RUN_UNTIL does:
PRESS 1 a 20 until 1d == 0 is a jump and its landing in one request.
A single request runs at most nine seconds of frames - 540 at
60fps, 450 at 50fps, and never more than 600 - because a reply is
waited for ten. An MCP client is told the command did not answer after
ten seconds and the frames run on regardless, so RUN_FRAMES, PRESS,
STEPS and RUN_UNTIL's [max frames] all refuse more than that outright
rather than failing later with hundreds of frames already run:
RUN_FRAMES answers "a frame count from 1 to 540; ask again to run
more" for a count of -5 and of 600 alike.
PRESS has a limit on every interface - nine seconds of frames over
MCP, 600 frames on the network and stdin interfaces - because it holds
input through every frame it runs and a press nobody is waiting for
would go on holding buttons down. RUN_FRAMES keeps the full ten minutes on the
network and stdin interfaces, which have no deadline, and leaves
nothing held if its reply is dropped - so that pair is the way to hold
a control for longer than ten seconds.
WATCH <label> <address> watches the byte at a system address, and
RUN_FRAMES, PRESS and RUN_UNTIL then carry it, as a line of
label, address and value after the command's own answer:
PRESS 1 right+a 4
x 7e0086 40
mode 7e0770 8
A step and the look that follows it become one request, rather than the step and then a read for each thing the assistant wants to know.
One request sets several - WATCH x 7e0086 mode 7e0770 - and takes
all of them or, where one is refused, none. WATCH with nothing
answers what is watched and what each byte holds now, off in place of
an address stops watching that label, and a label already watched keeps
its place in the list when its address changes; with nothing watched
it answers WATCH none. Values are decimal, 0 to 255 - or to 65535
for a high:low watch - as RUN_UNTIL takes them; addresses are hexadecimal. A label is up to 15 characters,
with no tab or newline in it. x 6d:86 watches two bytes as one value,
high:low, as conditions read them. Sixteen at once. Each is checked when it is
set - an address nothing maps is refused there -
and read afresh on every reply, so a core that moves its memory is
followed; one that stops mapping a watched address answers none for
it. All of them are dropped when content closes, since the next
content's addresses mean something else.
RUN_UNTIL <address> <condition> <value> [max frames] runs the content
until the byte at a system address meets the condition - ==, !=,
<, >, <= or >= against a value from 0 to 255, decimal or 0x
hexadecimal (ce & 0xF0 == 0x70, as STEPS and PRESS ... until
take them too; over MCP RUN_UNTIL's value is a JSON number) - and
answers with
how many frames ran, what WATCH watches, and what the byte holds.
Two addresses as high:low read two bytes as one value, 0 to 65535:
6d:86 >= 1800 waits for Super Mario Bros.'s Mario to pass x 1800,
which the game keeps as a page in one byte and a place on it in
another. & <mask> after the address compares only those bits, as a
game keeps its flags: 1d & 0x40 != 0; the value it answers is the
masked one.
MET 12
x 7e0086 52
VALUE 5
Where a client would otherwise run a few frames, read the byte and go
round again, this is one request. The address is the kind
GET_MEMORY_MAP gives and READ_CORE_MEMORY takes, and one nothing
maps is refused before any frame runs rather than after a wait that
could not have ended. Already meeting the condition answers MET 0.
The byte is looked up afresh every frame, as the watched ones are, so a
core that moves its memory is followed; one that stops mapping the
address while it is waited on ends the wait with an error.
Left to itself it waits about nine seconds of the content's own frames
- 540 at 60fps, 450 at 50fps - so the answer comes inside the
ten-second deadline at any frame rate, and
[max frames]asks for up to that many. When they run out first it answersWAITINGwith how far it got, so the next request carries on from there instead of the client being told it failed.
STEPS <step>[; <step>...] runs a stretch of play as one request. Each
step is run <frames>, press <player> <controls> <frames>, until <condition> or checkpoint, in order; up to four stop <condition>
entries anywhere in the list end it after any frame where one holds - a
death, the level's end - so neither plays out the rest. checkpoint
keeps the state STATE rollback returns to, where the list has got to,
so a stretch can mark its own retry point:
STEPS until 6d:86 >= 1500; press 1 a 20; until 1d == 0; stop e == 11
DONE 74
x 86 212
STEP 3
Two presses of the same button in a row get a frame with it let go
between them, so the game reads two taps rather than one long press -
also where one request ends on the press and the next starts with it.
That frame is the second press's own, not taken from it, and is not
needed where INPUT set held the button throughout or a frame has run
since.
It answers DONE when every step has run, STOPPED when stop held,
and WAITING when its nine seconds ran out first, each with the frames
run, what WATCH watches, and the STEP it ended on - so after
WAITING the client asks again with the steps from that one. 32
steps at most; the frames run and press ask for must fit in the
nine seconds, and an address nothing maps is refused before any frame
runs.
Queued, the content plays on between requests. STEPS <steps>|on
(queue: on) answers at once with QUEUED and the steps left to run,
and its steps go behind those still running, so the game does not pause
while the next stretch is planned; it pauses once they have all run.
Each list runs with its own stops - none where it has none - and counts
its own frames. A stop that held, a wait that ran out or a failure
ends the whole queue, lists behind it too.
The next reply, whatever the request, says how the queue ended, on
a PREVIOUS line after its own first one: PREVIOUS STOPPED 43 STOP 1 STEP 1, PREVIOUS WAITING 540 STEP 1 or PREVIOUS ERROR <why>, given
as previous - its STEP counts within the list that step came in,
stops aside. A queued STEPS then runs none of its own steps, which
would play on from a death: it answers DISCARDED with how many it
dropped, or QUEUED 0 where it brought none. Any other request runs as
asked. A request that waits - RUN_FRAMES, PRESS, RUN_UNTIL,
STEPS without on - while the queue still runs replaces it, and its
reply says so: PREVIOUS REPLACED <frames run> STEP <step>. Each
ending is told once.
A rollback, a state load, RESET and closing the content each end the
queue and forget what it came to, however they come - a hotkey, the
menu, a command; asked for as STATE or RESET, the reply says so:
STATE rollback, queue ended. With no steps it only asks. A queue that ran dry
says so: IDLE is how long, in milliseconds, the content has sat paused
since, waiting for more; a frame run meanwhile - the user unpausing -
ends it. A client that sees it knows it has fallen behind: two
stretches sent at once get it ahead again. Nine seconds bound each
step, not the queue: an until that has not held by then ends it
WAITING. It holds 64 steps and stops at most.
RUN_FRAMES <count> pauses the content, if it is running, and runs it
that many frames, one per frame advance, answering once the last has
run; it is left paused. Use it to let the game run on its own - a
cutscene, a fall - where PRESS is for holding something while it
does. Both are refused while the menu is open, without content, and in
achievements hardcore mode, and they, RUN_UNTIL and STEPS are the
same one job: a second of any of them replaces one still running, which is answered with an error, as it is when the content
closes.
INPUT set with RUN_FRAMES is still the way to hold something across
several steps - a direction held while reading memory between frames -
and to put a stick anywhere but centre.
INPUT set <player> <control> <value> holds a RetroPad button (a,
b, start, up and the rest; 1 holds it, 0 lets it go) or a stick
axis (left_x, left_y, right_x, right_y; -32768 to 32767, 0 lets
it go) for the core, over the player's own controller, until it is set
again, INPUT release [player] lets go of it, or the content closes -
the next content does not start with a button held for this one. Both answer with the
player, the buttons held and the axes held, tab separated, and none
for either where nothing is held. INPUT release with no player lets
go for every player and answers for the first of them. Achievements
hardcore mode refuses INPUT set. The core is given exactly what is
held: opposing directions are not cleaned and the D-Pad is not turned
with the picture, and under netplay the player is this machine's, so a
hold is sent like a press. INPUT show [player] answers in the same
shape without changing anything, which neither of the others can
do: one has to set something to answer and the other lets go before it
does.
Several controls join with + to be held together:
INPUT set 1 right+a 1 runs and jumps in one request, where two
requests would take two frames. Every control is checked before any is
held, so a combination with a name or a value wrong in it holds
nothing. PRESS takes the same combinations.
The running core's own options are CORE_OPTION. With no key, CORE_OPTION show lists every option as
key, value and description, tab separated; with a key it gives that
option's line with the values it takes after a further tab, separated
by |. CORE_OPTION set <key> <value> takes one of those values and
answers with the option's line; asking for the value it already has
changes nothing. Whether a change applies at once or on the next start
of the content is the core's to say.
GET_MEMORY_MAP lists the regions of the core's memory map, one per
line: the start address READ_CORE_MEMORY and WRITE_CORE_MEMORY take,
the length, the select and disconnect masks (hexadecimal), what the
region holds (system, save, video or other), rw, ro, or
none when nothing backs it, the byte order, and the address space
name. A region with a select mask answers every address that agrees
with its start in the selected bits, not only start to start plus
length.
A core that publishes no memory map - snes9x among them - still hands
its RAM over through retro_get_memory_data, and every memory tool reads
that instead: system RAM from address 0 and save RAM straight after it,
the layout RetroArch's achievements use when they know no console.
GET_MEMORY_MAP lists the two as system and save, in the address
space core. These are offsets into the core's RAM, not the console's
addresses: the SNES's work RAM at $7E0000 is 0 here, which is also the
address RetroAchievements' notes give for it. Other consoles' notes may
place RAM elsewhere - the NES's save RAM at 0x6000, say, is straight
after system RAM here. Reads run across from one
to the other, WATCH and conditions take them, and WRITE_CORE_MEMORY
writes them.
To find something to play, an assistant lists the playlists with
LIST_PLAYLISTS, reads one with GET_PLAYLIST (index, label, content
path and core path per entry, 200 at a time; MORE <next> gives the
argument for the next page, as in Nintendo - SNES.lpl 200), and loads
an entry with LOAD_CONTENT <core path>|<content path>. LIST_CORES
gives the installed cores and their paths.
An entry with no core of its own gives DETECT as its core path, and
LOAD_CONTENT takes an entry as it reads: DETECT, or no core at
all, loads the content with an installed core that supports it. Both
paths are checked before anything is unloaded, so content that cannot
be found and a core that is not installed are answered with what is
wrong while the running game keeps playing.
Where more than one installed core supports the content, LOAD_CONTENT
says so and leaves the choice: LIST_CORES with that same content path
answers the candidates as rows, so a client reads the list from the tool
whose job it is rather than out of an error message. Where none does,
LIST_CORES answers no rows, as it does when no cores are installed at
all.
Over MCP, playlist and first are separate parameters, so a name is
never mistaken for an entry number. On the network and stdin interfaces
the two share one line, where a trailing number alone is the entry to
start at: Atari - 2600 reads there as the playlist Atari - from
entry 2600, while Atari - 2600.lpl cannot be read as anything but the
playlist.
A tool whose work runs over later frames answers once that work is
through, with what came of it, or with the command's name, ERROR and
the reason:
LOAD_CONTENT,CORE start: the content's path once it runs; a core that fails to start is an error.CLOSE_CONTENT,CORE unload: once the content is closed. Requests sent while content loads wait for it.LOAD_CONTENTwithpausedon pauses the content once it has loaded, so nothing runs on between the load and the first step: a title screen's demo starting, say. The core has run a frame by the answer - two where no content was running before, as a core counts as running after its first - and a game may take a few more to set up its RAM, so run some before reading it. On the network and stdin interfaces<core>|<content>|ondoes the same, and is answered there too.STATE: once the state is applied or written.STATE checkpointkeeps one state in memory, not in a slot's file, andSTATE rollbackrestores it: the retry after a mistake, in one request where replaying the level took a dozen. WhatINPUT setholds stays held through it; a queuedSTEPSends, as it does on any load. The checkpoint lives as long as the content does; a rollback is refused while a replay records, as a load from a slot is.RESET: once the content is reset; withpausedon, paused after it before any frame runs, so the game has not set up its RAM yet. A queuedSTEPSends.REPLAY:play,seek,recordandcheckpointonce the replay has started or the seek or checkpoint has run;haltis a hotkey press, answered at once.SET_SHADER: the preset's path once it has compiled.
A tool that fails says why, as <NAME> ERROR <reason>, and the result
is marked isError. It is a JSON-RPC result, not a JSON-RPC
error: those are kept for a request the server could not run at all -
an unknown tool, invalid params, broken JSON. Whether a reply is a failure is the command's own
word, not something read out of its text: a screenshot path that holds
ERROR - a game named so - is no error, and a failure whose text says
nothing about one still is.
A content load is answered when it finishes, however long it takes:
the server is not polled while one runs, and requests sent meanwhile
wait for it. Other work that takes longer than ten seconds - a shader
that is slow to compile, say - is answered with an error saying so;
the work goes on, and GET_STATUS tells when it is through. A request still waiting for its answer when
the server goes is answered with an error rather than left without one.
A request over HTTP is at most 64 KiB, headers and body together, and a
larger one is answered 413; only POST /mcp and POST / are served.
Over stdio a line past 64 KiB is answered with a parse error and skipped
to its newline, and a \r before the newline is taken as part of it.
Batch requests are refused as invalid.
Hotkey tools (QUIT), and the hotkeys behind DISK and REPLAY halt, press for one frame. SCREENSHOT is the exception: it
takes the screenshot at once and answers when it has been written - with the
picture itself as image content (PNG, up to 4 MiB) and the file's path as
text, so a client can see the screen without reaching the file - or with
SCREENSHOT ERROR and the reason if it could not be.
GET_FRAME [size] is the look without the file: the content's frame
on screen now, scaled down to fit a square of size pixels (64 to
640, 320 when left out; never scaled up), answered as image content
with GET_FRAME 320x240 as its text. Nothing is written - no file, no
history entry, no notification - so it costs a client only the image.
It takes the frame the way SCREENSHOT does, from the GPU's read-back
for a hardware-rendered core, and is refused while another screenshot
is being taken. It is for what memory cannot say: a game whose RAM no
one has charted, or checking what the RAM says. It is not for the step
loop, where WATCH's numbers cost far less than a picture. The line
interfaces carry no image, so there it is refused, pointing to
SCREENSHOT.
Every tool carries hints for the client:
- read-only: only reports (
GET_STATUS,GET_FRAME,GET_LOG,LIST_CORES,LIST_PLAYLISTS,GET_PLAYLIST,READ_CORE_MEMORY,GET_MEMORY_MAP); - destructive: can lose unsaved progress or data, or loads code
(
QUIT,RESET,STATE,REPLAY,WRITE_CORE_MEMORY,CORE,LOAD_CONTENT,CLOSE_CONTENT,MENU).
A tool that is not read-only states destructiveHint, true or false,
since its default is true; a read-only one leaves it out, as it means
nothing there. openWorldHint is left at its default.
OPTION, INPUT and CORE_OPTION are neither: they write, but only to
the options and controls they list, and none of them loses progress.
Most clients ask before running a destructive tool. Keep that on.
A core path that is not a core is found out before anything is torn
down for it. CORE load and LOAD_CONTENT both probe the library
first - the same probe core scanning uses - and answer no core at <path> or <path> is not a libretro core. The core already loaded is
not probed. A stale library or something renamed would otherwise
unload the running core and then fail, costing the game that was
running.
Achievements hardcore mode
While RetroAchievements' hardcore mode is on, the server runs no tool:
every tools/call is answered as the tool's own failure, <NAME> ERROR achievements hardcore mode is on; the player can turn it off. Hardcore
achievements are the player's own, as the mode's ban on rewind, slow
motion, cheats and states already says. The handshake and tools/list
still answer, so a client can connect and learn why. When hardcore mode
takes effect - switched on, or a game loaded with it on - what a client
left playing stops with it, as slow motion does: a running or queued
step job ends, and what INPUT holds is let go. Turning hardcore mode
off is the player's, in RetroArch.
Security
An MCP client with the token can do what the tools allow, and CORE load
loads a library from any path: treat the token like a password.
- The server listens on
127.0.0.1and is reachable from this machine only. Changingmcp_server_bind_addressexposes it to the network; anyone who can reach the port and has the token then controls RetroArch. - Every request must carry the token. Requests without it get HTTP 401.
- A request from a web page is refused (HTTP 403) unless the page itself
is served from this machine, so a site cannot reach the server by
pointing a host name at
127.0.0.1. - To revoke a client's access, clear MCP Server Token: a new one is made on the next start.