Model Context Protocol Server

TEMU allows an AI agent to inspect and interact with the emulated system through built-in support for the Model Context Protocol (MCP). The server is provided by the Debugging plugin, together with the ContextManager and TCFServer models it builds upon. An agent can, for example, probe memory, read and write model registers, inject interrupts or UART traffic, and run or pause the simulation.

An MCP client can execute arbitrary TEMU commands. Only expose the server on a network you trust, and consider requiring an authorization token (see Authorization).

Prerequisites

The MCP server has two prerequisites:

The multi-level scheduler

Only the multi-level scheduler can run TEMU commands safely, without racing against the simulation.

TCF server

The MCP server runs on the event loop of the TCF server, so a TCFServer instance must be running before the MCP server is started.

Starting an MCP Server
import Debugging

# The scheduler must accept control ops. Just starting the scheduler
# does not yet run the simulation.
sched.start workers=1

# MCP runs on the TCF event loop. The context manager has to exist, but it
# does not need to be configured. If it is configured, the MCP server also
# exposes partitions, threads and source line mappings to the agent.
ContextManager.new name=cm0
cm0.attach board=board0
TCFServer.new name=tcf0
tcf0.contextManager = cm0
tcf0.start-server port=0

MCPServer.new name=mcp
# Causes a `temu_log*` per command executed by an agent:
mcp.config.logging = 1
mcp.start addr="127.0.0.1" port=9001 sched=sched tcf=tcf0

The server then serves the protocol over HTTP at the /mcp path, in this example at http://127.0.0.1:9001/mcp.

The start command takes the following arguments:

sched

The MultiLevelScheduler instance to control (required).

tcf

A running TCFServer instance (required).

addr

Address to bind (defaults to 127.0.0.1). Pass 0.0.0.0 to accept connections from other hosts, or from local Docker containers.

port

TCP port to bind. If omitted, or 0 is given, the operating system selects a free port. The port that was bound can be read back from the port object property.

Tools

The tool list is built when the MCPServer object is created. Only commands that are already registered at that point become tools, so the server object should be created after all other components.

Command Tools

Almost every global CLI command and every class command is offered as a tool, so an agent has access to the same functionality as a user at the TEMU CLI.

Global commands keep their name, for example memory-read or object-list. Class commands are named <Class>.<method>, for example Console.dump-traffic, and take an additional required this argument naming the object to call the method on.

Output that the command would have printed at the CLI is captured and returned as the tool result. This works for models that print through temu_log* or temu::outs() and temu::errs().

Some commands are deliberately not offered, for example:

  • Commands related to execution control (init-scheduler, object-run, object-step, object-trace and the scheduler classes). An agent controls execution only through the scheduler tools described below.

  • Object creation and destruction (new, delete), license, logging, plugin and configuration commands (license-, plugin-, config-, temu-, exec-*).

  • Commands that take interface references as arguments. An agent cannot call connect, but it can read existing interface connections.

In addition, the execute tool runs an arbitrary TEMU script fragment. It is a fallback for the cases that the individual tools do not cover. The tool description explicitly discourages the agent from using it.

Object and Property Tools

The read-property and write-property tools give direct access to the properties of any object, without going through the script interpreter.

Together with the object-list and object-info commands, this is normally the cheapest way for an agent to explore a machine configuration.

Scheduler Tools

Execution is controlled through three dedicated tools:

scheduler-run

Start or resume the simulation. The call returns immediately and the simulation keeps running in the background. An agent can pass a cycles or nanos argument to limit how long the simulation runs.

scheduler-stop

Pause the simulation.

scheduler-state

Report the run state of the scheduler (idle, running, stepping, …​), and the log messages that were captured since the last scheduler-run.

Since scheduler-run is asynchronous, an agent starts a run and then polls scheduler-state to see how far the target software has progressed. The agent can only read temu_log* messages, not stdout and stderr directly.

To let an agent read the console output of the target software as well, enable traffic recording on the console model. See Capturing Console Traffic. The agent can then use dump-traffic to read UART output and inject to send input to the UART.

Debugging Service Tools

The TCF services of the TEMU debugger are offered as tools named <Service>.<command>, which gives the agent operating-system-aware and DWARF-aware access to the target software.

Examples are Symbols.list, Symbols.findByName, Symbols.findByAddr, StackTrace.getChildren, StackTrace.getChildrenRange, LineNumbers.mapToSource and LineNumbers.mapToMemory.

These services are keyed by opaque, path-like context IDs. The debug context tree only exists once a board has been attached to a ContextManager, i.e. cm0.attach board=board0 in the example above. An agent discovers the available IDs by querying the tree, for example ContextQuery.query with the query /Boards/**.

Authorization

The server can require an HTTP bearer token from connecting clients:

mcp.authorization token="a-secret-token"

The command may be given several times to accept several tokens.

Client Configuration

The MCP server uses HTTP, so a client only needs the URL of the /mcp endpoint.

For gemini-cli, run:

$ gemini mcp add TEMU --transport http http://localhost:9001/mcp

For mistral-vibe, add this to ~/.vibe/config.toml:

mcp_servers = [
    {
        name = "TEMU",
        transport = "http",
        url = "http://localhost:9001/mcp",
        disabled_tools = []
    },
]