Skip to content
YggdraSIM

Run the MCP server

Give an AI assistant the YggdraSIM tool surface, so it can do the work an operator does rather than hand hex back and forth: decode an APDU or an ASN.1 structure, resolve a status word or spec section, lint a SAIP package or an eIM package, diff two session recordings, drive a card, and run batch commands in the operator shells.

On this page

31 tools, 4 reference resources, and 3 canned workflows. Eight operator shells are reachable through shell_run, covering 378 classified verbs -- every entry point in the project that has a batch mode.

The server speaks the Model Context Protocol over stdio and works with any MCP client (Claude Code, Claude Desktop, and other MCP-capable tools).

What it deliberately does not do is decide it is allowed to act. Every capability that changes something sits behind an opt-in an operator sets on the server entry, described under Access model.

Access model

The intent is that an agent can do what an operator can do, given the same information -- build a SAIP profile, install an applet, test an OTA envelope. What it cannot do is decide on its own that it is allowed to.

The server starts read-only, and three independent switches widen it. None implies another, and each is set on the server entry rather than per call, so the choice is persistent and visible.

Variable Off (default) On
YGGDRASIM_MCP_ACCESS reads only write also permits anything that changes state
YGGDRASIM_MCP_ALLOW_CARD nothing reaches hardware tools and verbs may reach a physical card
YGGDRASIM_MCP_ALLOW_SCRIPT_FILES RUN / SCRIPT refused an unverified command file may be executed

YGGDRASIM_MCP_ACCESS is a mode, not a flag: it reads write (also readwrite, read-write, rw) and treats everything else, including 1 and yes, as read-only. A truthy-looking value is not a request for write access.

The two axes are orthogonal on purpose. Write access without card access builds profiles and OTA envelopes on disk and never touches hardware. Card access without write access reads a card and cannot change it.

Card safety

Several tools reach a real card: pcsc_transmit locally, card_bridge_transmit through a relay, and the card_session_* tools through a connection they hold open. An MCP client is usually an agent acting without step-by-step review, and a wrong APDU is not always recoverable. PIN and PUK retry counters only decrement, an ADM key can block permanently, and a terminated card does not come back.

Card access is off by default

Nothing reaches a card unless YGGDRASIM_MCP_ALLOW_CARD is set. With it unset the card tools refuse with an explanation, and the rest of the 26 work normally.

Note what enabling it actually says: card_bridge_transmit reaches whatever relay URL it is given, so the flag covers the local reader and every rig this host can reach.

Changing a card needs write access as well

With card access on, APDUs are classified by instruction byte, and the two classes that change the card need YGGDRASIM_MCP_ACCESS=write:

Class Examples Needs
read SELECT, READ BINARY, READ RECORD, GET STATUS ALLOW_CARD
write UPDATE BINARY, UPDATE RECORD, INSTALL, STORE DATA ALLOW_CARD and ACCESS=write
destructive VERIFY, CHANGE PIN, RESET RETRY COUNTER, PUT KEY, DELETE, SET STATUS, DEACTIVATE FILE, STORE DATA carrying an eUICC memory reset ALLOW_CARD and ACCESS=write

An instruction the table does not recognise is classified as write, not read: not having seen an instruction is not evidence that it is safe.

Call apdu_risk to classify a command without sending it; it works with every gate shut, and reports the current access mode alongside the class.

A confirmation prompt before anything irreversible

When a destructive APDU is permitted, the server asks the client to confirm with a human first, naming the operation and the target. The distinction between write and destructive survives here even though both need the same opt-in: reflashing a file and terminating a card are not the same act.

This is defence in depth, never the only guard. Elicitation is an optional MCP capability, and a client that is itself an agent may answer the prompt without asking anyone. A client that does not support it at all is not an error; the server falls back to the environment gates. Those gates are what actually hold.

Credentials are never requested

The server never asks for a PIN, PUK, ADM key, or any other secret. The MCP SDK scopes in-band elicitation to non-sensitive data for good reason, and there is a sharper problem here: an agent client may answer a prompt itself, so a fabricated PIN would be submitted to the card and consume a real retry counter.

Secrets go in by path, configured out of band by a human:

{"apdu_url": "http://127.0.0.1:8642/apdu",
 "token_file": "~/.config/yggdrasim/card_bridge/8642.token"}

The server reads the file itself and enforces 0600 on it. The agent handles a filename, never a value, so nothing secret enters a tool argument or a transcript. Authenticated flows such as SCP03 follow the same rule: stage the keys as files first, then reference them by path.

A handful of shell verbs take key material as a positional argument -- DERIVE-OPC is the clearest -- and those are gated at the write tier rather than refused outright. Refusing would be theatre: if the caller supplied the key, it is already in the transcript. Prefer the by-path form where the shell offers one, and treat any batch that carries a secret inline as a batch whose transcript is now sensitive.

Tool annotations

Every tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), so a client can tell the difference between status_word_lookup and pcsc_transmit without reading this page and can prompt accordingly. 23 of the 31 tools are marked read-only; the seven that are not are pcsc_transmit, card_bridge_transmit, shell_run, card_backend_select, and the three card_session_* tools.

Session state

pcsc_transmit connects, transmits one APDU, and disconnects. No session survives between calls, so it suits stateless probes and cannot carry a secure-channel flow: the second APDU of an SCP03 exchange would arrive on a card that has forgotten the first.

There are two ways to keep state. card_session_open holds a connection locally and hands back a session id to transmit through. Or run a Card Bridge and use card_bridge_transmit: the bridge holds the reader and relays through it, which is also what reaches a remote rig. See Card Bridge over SSH.

Whatever the layers say: use a throwaway test card, not one carrying live credentials.

Install

python -m pip install -e '.[mcp]'

The mcp extra is opt-in: neither the base install nor [full] pulls it in, so a normal runtime never carries the server.

Standalone, without the rest of YggdraSIM

Most of the tools decode bytes and resolve identifiers, which needs no card stack. scripts/release/build_mcp_standalone.py generates a separate yggdrasim-mcp distribution carrying just those:

python scripts/release/build_mcp_standalone.py --wheel-out dist/
pip install dist/yggdrasim_mcp-*.whl          # decode, lookup, diff tools
pip install 'yggdrasim_mcp-*.whl[card]'       # adds the PC/SC tools

It declares only mcp, pyyaml, and asn1crypto, with pyscard optional because it needs a compiler and the PCSC headers. No Git dependencies, so a plain pip resolves it.

Fifteen of the twenty-six tools work from that install alone, nineteen with [card]. That includes driving a card: the transport chain is vendored, so card_session_open, card_session_transmit, and card_bridge_transmit all work without the rest of YggdraSIM. [card] adds the three that need a local PC/SC driver; the relay path needs no driver at all, so a standalone install with no pyscard can still drive a card through a Card Bridge or a Remote Lab rig.

Seven tools need the full install and report that they are unavailable, naming what is missing rather than raising: saip_lint and saip_diff need the SAIP stack; bpp_segment, metadata_lint, and eim_package_lint need the SCP11 code; runtime_status and shell_run need the full runtime. The simulated backend is also full-install only -- SIMCARD is a whole subsystem, so selecting sim on a standalone reports that plainly and points at the reader backend.

The distribution publishes a single yggdrasim_mcp package rather than re-providing Tools or SCP03, so it can be installed alongside the full yggdrasim without a file collision. The tree is generated on demand from these sources and is never committed, so it cannot drift from the code it is cut from.

Every degraded tool is still registered, so an agent discovers it and gets a reason instead of a missing capability it cannot ask about.

Register it with a client

For Claude Code:

claude mcp add yggdrasim -- yggdrasim-mcp

For a client that reads a JSON config, the equivalent entry is:

{
  "mcpServers": {
    "yggdrasim": {
      "command": "yggdrasim-mcp"
    }
  }
}

To enable card access for a supervised session, add the environment variable to that entry:

{
  "mcpServers": {
    "yggdrasim": {
      "command": "yggdrasim-mcp",
      "env": { "YGGDRASIM_MCP_ALLOW_CARD": "1" }
    }
  }
}

From a source checkout without installing, python -m Tools.YggdraMCP.server is equivalent.

Tools

Lookup

Tool Purpose
status_word_lookup resolve SW1/SW2, including the 61xx, 6Cxx, and 63Cx families
ber_tlv_lookup name a single BER-TLV tag with its spec citation
spec_section_lookup find a clause in the local spec library (docs/tel-docs/converted) and return its title, page file and a versioned citation; without the library, a short verified index
aide_registry_lookup resolve an application identifier
validate_identifier check an ICCID, IMSI, EID or MCC/MNC against the test ranges this project uses

Decode

Tool Purpose
apdu_parse split a command APDU into CLA/INS/P1/P2/Lc/data/Le
asn1_decode recursively decode BER/DER TLV or a full APDU into a named tree
sgp32_decode decode an SGP.32/SGP.22 response body: euicc_info1, notifications, rat_rules, eim_configuration, get_certs
bpp_segment show how a Bound Profile Package splits into ES10b segments per Annex M
apdu_risk classify an APDU as read, write, or irreversible without sending it

apdu_parse and ber_tlv_lookup answer narrow questions (header fields, one tag). asn1_decode parses a whole structure, resolving every nested tag against the GSMA/3GPP index with its spec source, so a complete EuiccInfo2 comes back as structure rather than hex. It tries BER/DER first and falls back to APDU interpretation, so a bare command APDU decodes too.

Files

Tool Purpose
saip_lint lint a SAIP package and return the YRL-* findings
saip_diff structurally diff two SAIP packages: added, removed, changed, moved
metadata_lint lint an SGP.22 profile metadata document
eim_package_lint validate an SGP.32 eIM package against the ES2+ schema
plugin_status report which optional plugin-backed capabilities are available
runtime_status report the runtime root, build flavor, and live service state
shell_run run a batch of operator-shell commands; some of these reach a real card
session_diff diff the APDU traces of two session recordings

saip_lint accepts the same inputs as Package > Open: binary DER, ASCII hex text, ASN.1 value notation, or transcode JSON. Excel workbooks are refused, because they are not SAIP packages; see the note on spreadsheet extensions in Build and Packaging.

session_diff takes two recordings written by the shell recorder; see Diff Two Session Recordings.

saip_diff bounds its response at 200 entries and reports how many were dropped; a whole-package diff can run to thousands of nodes.

Upstream pySim logs the construction of every file in a profile at DEBUG, which is over a hundred kilobytes of stderr per package load. Those loggers are raised to WARNING; set YGGDRASIM_MCP_UPSTREAM_LOG_LEVEL=DEBUG when actually debugging a decode.

Card

Tool Card access Purpose
pcsc_list_readers no enumerate local PC/SC readers
pcsc_transmit yes transmit a raw APDU to a local physical card (stateless)
card_bridge_transmit yes transmit through a Card Bridge or Remote Lab relay (keeps session state)
card_backend_status no report which transport the stack talks through, and what is open
card_backend_select for reader point the stack at a local reader or the simulator
card_session_open for reader open a session that survives across calls, and read its ATR
card_session_transmit for reader send one APDU through an open session
card_session_close no close one session, or all of them

Choosing the transport

Three paths reach a card: a local PC/SC reader, a relay, or the built-in simulator. card_backend_status reports which one is configured, where that setting came from, and every session this server holds. It reads with every gate shut, and reports whether a relay token exists rather than its value.

card_backend_select switches between reader and sim. Both need write access, because the choice outlives the call; selecting reader additionally needs card access, since it points the whole stack at hardware. persist is off by default -- with it on, the choice is written to the runtime settings file and every other YggdraSIM process picks it up.

Selecting sim is how an agent does card work with no reader present: the simulator answers real APDUs, so a SELECT/READ chain or a profile inspection runs end to end. The card gate does not apply to it, because there is no hardware to protect. Write access still does, because the simulator carries state.

Sessions

pcsc_transmit connects and disconnects around each APDU, so a secure-channel flow cannot work through it: the second APDU of an SCP03 exchange arrives on a card that has forgotten the first.

card_session_open holds one connection open and returns a session id and the ATR. Every card_session_transmit on that id runs on the same channel, so the selected file, the logical channel, and the secure channel all survive between calls. Each APDU is still classified individually, so a read-only server can drive a whole inspection sequence and refuse the one command that would change something.

Sessions expire after 10 minutes idle and at most 4 are held at once. The handle pins a reader and keeps the card powered, so an unbounded registry would leak both.

card_bridge_transmit reaches whatever rig its URL points at, so it sits behind the same opt-in as pcsc_transmit. Enabling card access is therefore not only a statement about the reader on this machine; it is a statement about every relay this host can reach. For a Remote Lab rig the token file holds the session token, not the bridge's own token.

Running shell commands

These shells reach a real card

With every opt-in set, verbs reachable through shell_run can install applets, write keys, send an OTA envelope, export a key bag, and disable or delete a profile. None of that can be undone. Use a throwaway test card, never one carrying live credentials.

Nothing reaches a card, and nothing changes state, unless you set the environment variables below. They are off by default and stay off until an operator turns them on deliberately.

shell_run executes a non-interactive batch in an operator shell, so an agent can drive a workflow rather than only inspect single files:

shell="profile_package"     USE /abs/profile.der; INFO; TREE; LINT; EXIT
shell="scp80"               SET /abs/keys.json; BUILD; EXIT
shell="scp11_eim"           EIM-PACKAGE /abs/pkg.json; EIM-PACKAGE-LINT; EXIT
shell="suci_tool"           STATUS; GENERATE secp256r1; DUMP; EXIT
shell="scp03"               SELECT 3F00; READ; INFO; EXIT
shell="scp11_live"          GET-EID; GET-EUICC-INFO2; LIST; EXIT
shell="scp11_relay"         GET-EID; GET-EUICC-INFO2; LIST; EXIT
shell="scp11_local_access"  LIST; PROFILE; METADATA; EXIT

All eight operator shells are exposed, covering 378 classified verbs:

Shell Opens a reader at startup Verbs Purpose
profile_package no 61 SAIP package inspection and authoring
scp80 no 15 OTA: build an envelope offline, or SEND it to a card
scp11_eim no 74 SGP.32 local eIM: author, lint, and issue eIM packages
suci_tool no 11 SUCI key generation and public-key export
scp03 yes 81 card admin: filesystem, registry, GlobalPlatform
scp11_live yes 50 SGP.22/SGP.32 profile download and eUICC management
scp11_relay yes 50 the live shell under its legacy SCP11.relay entry point
scp11_local_access yes 36 local eUICC profile management over ES10

scp11_relay is the compatibility namespace of scp11_live: every module under SCP11/relay/ aliases its SCP11/live/ counterpart, so the two shells register the same verbs and share one classification.

scp80 and scp11_eim are the two that split the axes apart. Building an OTA envelope or authoring and linting an eIM package is offline work that needs write access and no card. The verbs that put those artefacts on a card -- SEND, SENDRAW, OTA in scp80, and the issue / ISDR / profile verbs in scp11_eim -- each carry their own card check even though the shell itself opened no reader.

Each shell's verb set is read from that shell's own command table, and a test compares the two in both directions on every run. A verb the shell registers but the gate does not classify is refused as unknown, so the failure mode is a capability going missing rather than an unguarded one.

The gates

A shell that opens a reader at startup needs YGGDRASIM_MCP_ALLOW_CARD, checked before the process starts. SCP03 connects to a reader during startup, so even HELP would touch hardware; refusing early means it never gets that far. Individual verbs that reach a card from an otherwise offline shell are gated the same way.

Verbs are allow-listed, not deny-listed. SCP03 alone carries 81 classified verbs. Read verbs run at any access level; anything that changes state needs YGGDRASIM_MCP_ACCESS=write. An unrecognised verb is refused rather than assumed harmless, and a refusal anywhere blocks the whole batch before the process starts.

Classification follows the leading verb, so a verb that dispatches its own subcommands is classified by the most dangerous thing it can reach: TOKENS sits at the write tier because TOKENS SET writes, even though a bare TOKENS only lists. Use the dedicated read verb where one exists -- LIST-TOKENS rather than TOKENS -- to stay inside read-only access.

--log <file> makes a read a write. Every shell appends a command's output to the file a --log modifier names, on the host the server runs on, so the gate takes the modifier off before it reads the verb and files a read verb that carries one under the write tier.

Verbs whose payload is never classified need their own opt-in. RUN and SCRIPT take a file of commands; RAW passes its arguments straight through to the underlying tool. In each case the gate cannot see what will actually run, so every other rule stops applying. Set YGGDRASIM_MCP_ALLOW_SCRIPT_FILES when you specifically want an agent to run something you have not had classified -- write access alone does not grant it.

Interactive verbs are refused at every level. A batch has no terminal, so a verb that opens a menu or prompts for input would hang until the timeout rather than fail. This covers more than the obvious TUI entry points: SCP03's PUT-KEY, SET-STATUS, and MANAGE-PIN are wizards, and scp80's ADMIN hands the reader to the SCP03 shell's own REPL.

Enabling it

Opt in on the MCP server entry, so the choice is persistent and visible rather than made per call:

{
  "mcpServers": {
    "yggdrasim": {
      "command": "yggdrasim-mcp",
      "env": {
        "YGGDRASIM_MCP_ACCESS": "write",
        "YGGDRASIM_MCP_ALLOW_CARD": "1"
      }
    }
  }
}

Drop YGGDRASIM_MCP_ALLOW_CARD for a server that authors profiles and OTA payloads but cannot touch hardware -- that combination covers most of the build-side work with none of the irreversible risk. Add YGGDRASIM_MCP_ALLOW_SCRIPT_FILES only when you intend an agent to run unverified command files.

Two things to know

Pass absolute paths. A shell resolves a relative path against its own profile and transcode directories, not the working directory, so a relative argument can silently act on a different package. The tool flags any relative path argument and reports when the shell logged a missing path.

State does not survive between calls, since each batch is a fresh process. Put a whole flow in one batch.

Ambiguity resolves upward. Where a verb's own help text left its risk open -- a package-issuing verb whose JSON the gate never reads, a flow whose steps the remote side chooses -- it sits at the destructive tier rather than the write tier. Guessing downward for a card shell is how an agent wipes one.

Service state is read-only

runtime_status reports the runtime root, build flavor, and whether the HIL bridge and Remote Lab have live state. It does not start or stop anything. Stopping a rig mid-session is a different class of risk from a bad APDU, and the value does not justify handing that to an agent.

Rig entries come back through the registry's redacted view: it reports whether a token file exists, never its path or contents.

What is not exposed

The card, profile, and eUICC surfaces are covered end to end. Of the project's other entry points, these are reachable only from a terminal:

Entry point Why
yggdrasim-gui, yggdrasim-web-server long-running services with their own UI
yggdrasim-hil-bridge, yggdrasim-hil-supervisor rig services; lifecycle is an operator decision
yggdrasim-lab-agent, yggdrasim-card-bridge daemons; the MCP is a client of these, not their manager
yggdrasim-profile-autoload watches for card insertion, so it never returns
yggdrasim-apdu-fuzzer, yggdrasim-eum-diag no batch mode, and the fuzzer's own allow-list gate is the right place for that decision

Every entry point with a batch mode is exposed. The services are deliberate: starting and stopping a rig is a different class of risk from a bad APDU, and a watcher that never returns cannot answer a tool call. The last row has no --cmd, so there is nothing to classify.

Resources

Reference tables an agent can read whole instead of spending a tool call per lookup:

URI Contents
yggdrasim://reference/status-words every status word the server can name
yggdrasim://reference/ber-tlv-tags BER-TLV tags with spec citations
yggdrasim://reference/spec-sections the verified clause index spec_section_lookup falls back to without the spec library
yggdrasim://reference/test-identifier-ranges the test ranges to use instead of real allocations, each with its source

Prompts

Canned workflows that chain the tools in a sensible order:

Prompt Use when
triage_failed_profile_download an SGP.22/SGP.32 download failed and you want the cause, not a guess
explain_apdu_exchange you have one command/response pair and want it read back in full
review_profile_package you want a SAIP package triaged into things actually worth fixing

These are deliberately generic. Anything encoding operator specifics -- real PLMNs, house profile rules, rig inventory -- belongs in a private plugin rather than the published server, the same split the vendor-quirk configuration uses.

Private extensions

A plugin under the runtime root can add its own tools, resources, and prompts by registering the mcp_extensions capability:

class OperatorMcpExtensions:
    def register(self, mcp) -> None:
        @mcp.prompt()
        def house_profile_review(file_path: str = "") -> str:
            return f"Review {file_path} against the house rules ..."


def register_plugins(manager) -> None:
    manager.register_capability("mcp_extensions", OperatorMcpExtensions())

Plugin loading is opt-in, because a plugin is executable Python from the runtime root:

YGGDRASIM_ALLOW_PLUGINS=1 yggdrasim-mcp

YGGDRASIM_DISALLOW_PLUGINS=1 hard-locks the loader and wins over the opt-in.

The server starts either way. A plugin that is absent, unhealthy, or raises is logged and skipped rather than taking the server down with it. A plugin tool that drives a card must call card_access_allowed() itself; see Plugin Contract.

Capabilities are gated on the plugin being there

An agent should not have to discover a missing capability by failing. Call plugin_status to see what is available:

{"extensions_active": true,
 "plugin_tools": ["workbook_to_saip", "operator_plmn_lookup"],
 "plugin_loading_enabled": true}

Built-in tools that depend on a plugin answer differently in each case rather than emitting one fixed refusal. saip_lint on a workbook is the worked example, because Excel-to-SAIP generation is not part of the published core:

  • no plugin -- reports plugin_available: false and how to install one
  • plugin loaded -- reports plugin_available: true and names the tool to call

A provider can set a workbook_tool attribute naming its converter, and that tool is listed first. Without it the core lists every tool the plugin added, since it cannot know which one handles a workbook.

Validation

Confirm the server starts and the client sees it:

yggdrasim-mcp </dev/null

It exits immediately on a closed stdin, which is enough to prove the entry point and the mcp extra resolve. If the extra is missing you get a one-line install hint instead of a traceback.

Confirm the gates are where you expect. Ask the assistant to call apdu_risk on 80E400000A (a DELETE); it should report destructive and would_be_sent: false without touching anything.

With the opt-in unset, ask it to transmit an APDU: it should come back with Card access is disabled, naming the environment variable. With YGGDRASIM_MCP_ALLOW_CARD=1 but not the destructive flag, a SELECT should go through while a VERIFY is refused as irreversible.

Security rules

  • Keep YGGDRASIM_MCP_ALLOW_CARD unset for unattended sessions. It gates both the local reader and every relay this host can reach.
  • The file tools read any path you give them. Point them at captures and fixtures, not at a home directory.
  • Tool output flows back to a model provider. Treat an APDU trace the same way you would treat it in a bug report: it can carry PINs and operator secrets.
  • The server binds nothing. It speaks stdio to its parent process only, so there is no listening port to firewall.