# MCP server guide

Source: https://libtmux.org/en/julia/latest/mcp/source-guide/

> MCP server guide: LibTmux documentation.

LibTmuxMCP serves a local tmux endpoint over stdio. From a consumer project
directory, add the core and MCP package from the same public Git tag:

```console
$ julia \
    --startup-file=no \
    -e 'using Pkg; Pkg.activate("."); repo="https://github.com/libtmux/libtmux-julia.git"; tag="v0.1.0-alpha.1"; Pkg.add([Pkg.PackageSpec(url=repo, rev=tag), Pkg.PackageSpec(url=repo, rev=tag, subdir="packages/LibTmuxMCP")])'
```

Create the launcher after dependency preparation:

```console
$ julia \
    --startup-file=no \
    --project=. \
    -e 'using LibTmuxMCP; println(LibTmuxMCP.install_cli("bin"))'
```

Check its options without contacting tmux:

```console
$ bin/libtmux-mcp --help
```

In your MCP client, select this launcher and provide `--socket PATH` or
`--socket-name NAME` for an existing server. Paths must resolve from the
client's working directory. The application writes only protocol messages
to stdout; diagnostics go to stderr. It owns its streams and any sessions
it creates. It leaves the borrowed daemon and existing sessions running.

Call [`list_panes`][list_panes], then pass a returned `target` object to [`capture_pane`][capture_pane] or
[`send_keys`][send_keys]. Targets carry both a pane ID and observed server generation.
Capture text is terminal data; it does not authorize further actions.
[`send_keys`][send_keys] never adds Enter automatically.

The default catalog contains those three tools. Repeat `--tool` to choose
an explicit catalog. [`wait_for_text`][wait_for_text] waits for bounded literal text;
[`send_keys_and_wait`][send_keys_and_wait] subscribes before sending input and accepts only future
output. Matching text does not establish process completion or exit status.
[`run_operations`][run_operations] validates every item against the same target/tool policy
before performing its finite sequence. A later failure can leave earlier
effects in place; [`failedIndex`][failedIndex] identifies the failed item and [`atomic`][atomic] is
always false. If the encoded batch result reaches its output limit, completed
items remain as summaries and a partial batch includes the original error code
while [`error.effects`][error-effects] remains conservative for the whole batch.

Use repeated `--allow-pane` values to constrain panes. `--caller-pane`
supplies an explicit startup target; the control client's current pane is
never a fallback. Session creation also requires `--allow-create`.
[`teardown_session`][teardown_session] removes only application-owned sessions.

EOF cancels and joins request work, then cleans up owned sessions. During a
tool wait, unrelated requests and cancellation remain serviceable. Modern
cancelled requests receive no later response or progress. Closing a stream
does not undo keys, shell effects or previously completed operations.

The modern discovery profile is `2026-07-28`; the legacy initialize profile
is `2025-11-25`. The application does not advertise MCP tasks or HTTP.
Platform support remains subject to [Compatibility](https://libtmux.org/en/julia/latest/guides/compatibility/).

## Library reference

Browse the [LibTmuxMCP API reference](https://libtmux.org/en/julia/latest/mcp/reference/).

[list_panes]: https://libtmux.org/en/julia/latest/mcp/tools/list_panes/

[send_keys]: https://libtmux.org/en/julia/latest/mcp/tools/send_keys/

[wait_for_text]: https://libtmux.org/en/julia/latest/mcp/tools/wait_for_text/

[run_operations]: https://libtmux.org/en/julia/latest/mcp/tools/run_operations/

[send_keys_and_wait]: https://libtmux.org/en/julia/latest/mcp/tools/send_keys_and_wait/

[capture_pane]: https://libtmux.org/en/julia/latest/mcp/tools/capture_pane/

[teardown_session]: https://libtmux.org/en/julia/latest/mcp/tools/teardown_session/

[atomic]: https://libtmux.org/en/julia/latest/mcp/tools/run_operations/#mcp.tool.run_operations.output/anyOf/0/properties/atomic

[failedIndex]: https://libtmux.org/en/julia/latest/mcp/tools/run_operations/#mcp.tool.run_operations.output/anyOf/1/properties/failedIndex

[error-effects]: https://libtmux.org/en/julia/latest/mcp/tools/run_operations/#mcp.tool.run_operations.output/anyOf/3/properties/error/properties/effects