MCP Server Reference¶

The operations LionAGI exposes to an MCP client, and the one tool they are reached through.

Purpose and transport¶

li mcp (equivalently python -m lionagi.mcp) starts an MCP server that speaks over stdio. There is no HTTP listener and no port to configure: the client launches the process and talks to it on its standard streams.

The server is a control plane over the li CLI, not a second implementation of it. Spawn and job verbs run li as a detached subprocess and keep a job record beside it; the remaining verbs run li <path> --machine and return the versioned envelope that command emits. A verb exists here only because it was registered, so adding a command to the CLI does not widen this surface.

It advertises one tool, request. Every operation is a namespaced verb passed to that tool rather than a tool of its own, because an advertised tool schema is sent to the model on every request in every session for as long as the server is registered. A verb's parameters are fetched by asking for them.

Install and client registration¶

The server needs the optional mcp extra:

pip install 'lionagi[mcp]'

Importing lionagi.mcp does not pull that dependency. Only serving does, so a missing extra surfaces when you run li mcp, with a message naming the install command.

Register it with any MCP client, for example in an .mcp.json:

{
  "mcpServers": {
    "lion": { "command": "li", "args": ["mcp"] }
  }
}

The key in mcpServers is your client's local name for the entry, and it is what your client addresses the server by. The name the server reports over the protocol is lion. Earlier builds reported lionagi, which is the name older registrations and logs show.

The request tool¶

request takes two optional inputs:

Passing neither is an error that says so. Exceeding the op limit is an error naming the count, never a truncation that would run part of a batch.

Result contract. Ops run in order, and a failing op does not stop the ops beside it. The reply is:

{
  "status": "success",
  "ops": [
    {"ok": true, "op": "job.status", "result": {"...": "..."}}
  ]
}

status is "success" when every op succeeded and "partial" when any op did not. A per-op failure never fails the call, so the caller must check each ok. A failed entry carries error instead of result, with a kind and a message, and a rejected op also carries the schema it was judged against, so a wrong parameter tells you the right shape in the same reply.

Argument validation is closed: an unknown or misspelled parameter is refused by name rather than ignored. Every value comes back as raw machine JSON, with no relative timestamps, formatted durations, or tables.

Asking what exists¶

help=true returns the catalog. Trimmed to its envelope, the reply looks like:

{
  "verbs": [
    {
      "verb": "agent.submit",
      "summary": "Run one agent on one task as a detached background run.",
      "required_unenforced": ["query"],
      "schema_fingerprint": "ae06438e99123763"
    },
    {
      "verb": "schedule.apply",
      "available": false,
      "summary": "Reconcile a whole ScheduleSet file into the store, atomically.",
      "cli_path": "schedule apply"
    }
  ],
  "verb_count": 70,
  "available_count": 44,
  "max_ops": 8,
  "help_usage": "help=true returns this catalog; help='<verb>' returns that verb's full parameter schema; ...",
  "synonyms_removed_after": "2026-09-30"
}

An entry states only what it cannot be read without. available and required are omitted at their defaults, so a verb with neither key is available and takes no required parameters. A verb that is not served here says so and names the cli_path that does run it, rather than repeating why; help='<verb>' returns that reason. The one entry that carries a reason inline is a verb whose schema failed to build, which reports a defect in this server rather than a deliberate exclusion.

help='<verb>' returns that one verb's full parameter schema:

{
  "verb": "job.status",
  "schema": {
    "type": "object",
    "properties": {
      "run_id": {
        "type": "string",
        "description": "Id of a background run as returned by a submit verb (format YYYYMMDDTHHMMSS-<6hex>). An id with no job record answers with known=false rather than failing."
      }
    },
    "additionalProperties": false,
    "required": ["run_id"],
    "title": "job.status",
    "description": "Current state of a background run: liveness, job record, CLI manifest."
  }
}

A spawn verb's help also returns a schema_fingerprint, which that verb's ops must carry. help={"verb": "<verb>", "playbook": "<name>"} additionally resolves that playbook's own declared arguments into the schema.

The catalog¶

44 verbs are reachable. Both tables in this section are checked against the registry by the test suite, so a verb added or withdrawn without updating them fails a test rather than going unnoticed. The registry is the authority; ask it directly with:

python -c "from lionagi.mcp import verbs as v; print(len(v.VERBS)); [print(n) for n in sorted(v.VERBS)]"

There is deliberately no parameter table here. A verb's parameters are projected from the CLI parser at call time, so a table written by hand would drift away from what the server actually accepts. Ask for the parameters instead, with help='<verb>', and you get the schema the call will be validated against rather than a copy of it.

Operations the surface does not offer¶

Twenty-six further names are catalogued as unavailable, each with its reason. They are not omissions: a caller that asks what exists gets the name and why it cannot be called, which is a different answer from the name never having been considered. The right-hand column below abbreviates the reason; help=true returns each one in full.

The largest group is no machine result: the CLI path emits no versioned machine result (li <path> --machine), so there is nothing to return that is not scraped console text. Scraping would make a command's console wording an API contract, so the fix belongs in the CLI, where the command gains a machine-result seam. The others are refusals on their own terms rather than gaps waiting to be filled — a write whose effect no machine result can describe, a path that would grant the calling agent a right it did not have, a control-plane signal whose effect lands on a running flow rather than in a reply, or a long-lived process that never returns at all.

Asking for one of these inside ops returns a catalogued answer rather than a bare unknown-verb error: the op comes back ok=false with an unavailable error carrying that verb's reason and summary. A name that was never registered at all is a not_found error instead, pointing you at help=true.

Separately, a small set of CLI paths that grant privilege to the caller has no verb at all, and no verb accepts opaque argv, so there is no route to them through this surface.

Worked example¶

Submit an agent, then observe it. First ask for the schema, because a spawn verb's op must carry the fingerprint that help returns. The fingerprint below is illustrative: it tracks the verb's current schema, so always send the one your own help call returned rather than a value copied from here.

{"help": "agent.submit"}

{
  "verb": "agent.submit",
  "schema": {"type": "object", "properties": {"prompt": {"...": "..."}}, "...": "..."},
  "schema_fingerprint": "947259f8208faddc"
}

Then submit:

{
  "ops": [
    {
      "op": "agent.submit",
      "args": {"prompt": "Summarise the changes on this branch.", "agent": "reviewer"},
      "schema_fingerprint": "947259f8208faddc"
    }
  ]
}

The reply carries the allocated run_id. Poll it, or read what it wrote:

{"ops": [{"op": "job.status", "args": {"run_id": "<run_id>"}}]}

{"ops": [{"op": "job.output", "args": {"run_id": "<run_id>"}}]}

To block instead of polling, use job.wait, which observes runs until they are terminal or the window closes and returns partial results rather than a bare boolean. Because ops run in order in one call, a status read and an output read can travel together:

{
  "ops": [
    {"op": "job.status", "args": {"run_id": "<run_id>"}},
    {"op": "job.output", "args": {"run_id": "<run_id>"}}
  ]
}

Check each entry's ok: the second can fail while the first succeeds, and status would then be "partial".

Terminal state of a background run¶

job.status, job.list and job.wait all resolve through one classification path, so no two of them can disagree about the same run. Branch on terminal and outcome; status is an open producer vocabulary and is for display.

outcome is the closed set succeeded | failed | cancelled | indeterminate. indeterminate paired with reason_code: "process_gone_without_outcome" is how a run ends when an observation positively established that its process is gone — the recorded pid held no process, it disappeared between two probes, or a live process holds the number and started at a different time — and no authoritative outcome was ever reported for it. Nothing survived to write one, so the run is ended here rather than left waiting forever.

That end is not a failure. The work may have had its intended effect before the process died. Consumers must not map it to failed, to success, or to cancellation, and must not retry it automatically: an unreported external side effect may already have committed.

Three fields describe such an end:

An unknown conclusion — a pid the OS cannot be asked about, an identity probe that was denied or unreadable — never ends a run. Those stay non-terminal and advisory (possibly_orphaned), and job.wait reports them under stopped_without_end.

finished_at on a run ended this way is when the end was established and recorded, not when the process exited, which nothing surviving can report. Any duration derived from it is an upper bound on how long the run actually ran.

job.wait's all_terminal means every valid requested run has a recorded end, including indeterminate ones. It does not mean every run succeeded or reported an outcome — read each entry's outcome for that.

Compatibility¶

An earlier version of this server advertised one tool per operation. Those flat names are still accepted as synonyms inside ops and resolve silently to their namespaced verb:

They exist for callers already scripted against them, not as something new callers should learn, which is why they do not appear in the catalog. They will be removed after the date the catalog reports as synonyms_removed_after, currently 2026-09-30. Write new calls against the namespaced verbs.

If your client shows a single entry in tools/list, that is correct and current. The operations are behind request, and help=true lists them.