Remote terminal access for MCP agents: create connection invitations, run commands, and manage interactive sessions on authorized macOS, Linux, and Windows computers. Open source, with one-command client onboarding.
Scored across 7 tools
The client pair (create_client, list_clients) and the session quartet (start/read/write/stop) are clearly separable, and execute_command is distinguished from sessions by being non-interactive. The only mild confusion is that create_client's description embeds most of list_clients' polling workflow, so an agent must read both to understand which tool drives the wait loop.
All names are lowercase snake_case with recognizable verbs, but the convention flips by resource: clients use verb_noun (create_client, list_clients) while sessions use noun_verb (session_start, session_read). It is predictable within each group, just not uniform across the set.
Seven tools is well-scoped for a remote device/session control server, and each one maps to a distinct step (invite, list/wait, execute, start, read, write, stop). Nothing feels redundant or padded.
The interactive session lifecycle is complete, but the client side is thin: there is no revoke/delete client token, no way to list active sessions or inspect a session, and no explicit way to cancel an invitation or disconnect a device. Agents must rely on timeouts and expiry rather than explicit operations.
Create a client connection token and a 15-minute invitation. Set multi_device=true for multiple simultaneous devices and a reusable invitation; otherwise the invitation is single-use and only one device may connect. First show display_text including both platform commands in a progress message, then follow next_action: call list_clients with client_token and wait_ms=20000 repeatedly until a device connects, the invitation expires, or the user cancels. Do not end the turn after showing the invitation or after an empty result. Immediately notify the user when a device connects. Use client_id to target devices for multi-device tokens. Session tools use session_id after starting a session. Treat tokens and commands as credentials and share privately. Saying you are waiting is insufficient: the same response must actually call list_clients; invitation creation alone does not complete this task.
| Name | Required | Description | Default |
|---|---|---|---|
| multi_device | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so thoroughly: it discloses the 15-minute invitation lifetime, multi_device versus single-use behavior, polling requirements, notification expectations, and credential privacy. It also clarifies a non-obvious operational rule: the same response must actually call list_clients rather than merely saying the agent is waiting.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and the key multi_device distinction, then moves into workflow guidance. It is somewhat long and repeats the instruction not to end the turn, but most sentences carry useful operational or security context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a complex connection workflow, one optional parameter, no annotations, and an output schema, the description supplies the orchestration details an agent needs: display_text handling, next_action polling with list_clients, stop conditions, notification behavior, and credential handling. It does not need to explain return values because an output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, multi_device, is fully explained despite 0% schema description coverage: true enables multiple simultaneous devices and a reusable invitation, while false makes the invitation single-use and limited to one device. This adds material meaning beyond the bare boolean schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Create a client connection token and a 15-minute invitation.' It also distinguishes the tool's role from siblings by explaining that list_clients is used afterward for polling and session tools use session_id once a session starts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear post-call workflow: show display_text, then repeatedly call list_clients with client_token and wait_ms=20000 until a device connects, the invitation expires, or the user cancels. It also says not to end the turn prematurely and to notify the user when a device connects, though it does not explicitly state when not to use create_client versus session_start or execute_command.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a non-interactive command and return output when it finishes.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory on the target device. Each command starts a fresh shell; use cwd for subsequent commands instead of relying on a previous cd. | |
| env | No | Environment overrides for this command, merged with the client environment. Values must be strings. | |
| command | Yes | Shell command | |
| client_id | No | Six lowercase letters or digits from list_clients. Required for multi-device tokens, even when only one device is online; optional for single-device tokens. | |
| timeout_ms | No | Execution timeout in milliseconds, up to 86400000 (24 hours). 0 disables the timeout. Default: 60000 for execute_command, 0 for session_start. | |
| client_token | Yes | Target client connection token (required when authenticated with the management key) |
| Name | Required | Description |
|---|---|---|
| error | No | |
| stderr | Yes | |
| stdout | Yes | |
| canceled | Yes | |
| exit_code | Yes | |
| timed_out | Yes | |
| truncated | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description must carry the full behavioral burden. It discloses that execution is non-interactive and blocks until output is returned, but it does not describe arbitrary-code execution risks, permission scope, side effects, or that each command runs in a fresh shell (that detail is only in the schema).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no wasted words. It is efficient, though its brevity leaves important behavioral context to the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained. But for a high-impact command-execution tool with no annotations and six parameters, the description should clarify that it runs arbitrary shell commands, the synchronous blocking model, and how it relates to the session tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents command, cwd, env, client_id, timeout_ms, and client_token in detail. The description adds no parameter-specific meaning beyond the schema, which is acceptable but not value-adding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Execute a non-interactive command') and adds the synchronous return behavior. It does not differentiate itself from session_* siblings, despite those tools being obvious alternatives for interactive or persistent shells.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Non-interactive' implies the tool is for one-shot commands rather than persistent sessions, which hints at the session_* alternatives. However, it never explicitly says when to use this tool versus session_start/session_write or mentions prerequisites like client selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List online devices belonging to this client_token. Set wait_ms=20000 to wait server-side while no device is online; a connection returns immediately. After creating an invitation, show display_text in a progress message and keep calling with wait_ms=20000 until the target connects, the invitation expires, or the user cancels. An empty result is only a wait timeout: continue waiting without ending the turn or asking the user to check. Immediately notify the user when connected. With wait_ms omitted or 0, return a snapshot immediately. Use client_id to execute commands or start sessions. For multi-device tokens, any online device completes the wait; use snapshots to discover additional devices.
| Name | Required | Description | Default |
|---|---|---|---|
| wait_ms | No | Wait up to this many milliseconds while no device is online (0-20000, default 0). After creating an invitation, use 20000 and repeat empty results until connection, invitation expiry, or user cancellation. | |
| client_token | Yes | Target client connection token (required when authenticated with the management key) |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden and does so well: it discloses long-poll semantics, the 20s server-side cap, that an empty result means timeout rather than 'no devices', that the agent must not end the turn or ask the user to check, and that it must notify on connection. These are non-obvious behavioral traps that structured fields do not cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then the waiting protocol; nearly every sentence carries operational instruction. There is mild redundancy between the invitation-loop sentence and the later 'empty result is only a wait timeout' sentence, but it reinforces rather than wastes space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter polling tool with no annotations, the description covers mode selection, timeout semantics, empty-result interpretation, notification duty, and multi-device discovery. An output schema exists, and the description still flags display_text for progress messaging, so nothing an agent needs to call and interpret this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3; the description nonetheless adds value by tying wait_ms to a concrete workflow (20000 after creating an invitation, 0 for snapshot) beyond the schema's parameter-level text. Minor deduction for referencing 'client_id' where the actual parameter is client_token, which slightly muddies which value to pass onward.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource plus scope: 'List online devices belonging to this client_token.' It also routes the agent onward ('Use client_id to execute commands or start sessions'), so siblings like execute_command and session_start are clearly separated from this discovery/lookup tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to guidance for both modes: wait_ms=20000 while waiting for an invitation connection, omit or set 0 for an immediate snapshot. It also prescribes the full operational loop (keep calling until connected, expired, or cancelled) and explains multi-device behavior, leaving little to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read new output while the session is running. Supply next_cursor from the previous read; wait_ms can long-poll for output.
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | Byte cursor, initially 0 | |
| wait_ms | No | Wait up to this many milliseconds for output | |
| session_id | Yes | Session identifier | |
| client_token | Yes | Target client connection token (required when authenticated with the management key) |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool reads new output while the session is running and that wait_ms enables long-polling, which implies read-only and blocking behavior. But it omits error conditions (e.g., if the session has ended), authentication requirements, and rate limits, leaving significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler. The purpose is front-loaded, followed by key parameter guidance, and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given four parameters, an output schema, and no annotations, the description covers the purpose and the critical cursor/wait_ms usage. It does not address session-lifecycle edge cases or auth details, but the output schema relieves the need to explain return values, making it largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, setting a baseline of 3. The description adds meaningful usage context by specifying that cursor should come from the previous read (though it calls it 'next_cursor' while the schema calls it 'cursor') and reiterates that wait_ms can long-poll, which goes slightly beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Read) and resource (new output) with the scope 'while the session is running', making the tool's purpose immediately clear. It does not explicitly name a sibling tool like execute_command as an alternative, but the action is distinguishable from session_write and session_start/stop.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance on parameter usage: supply next_cursor from the previous read and use wait_ms for long-polling. However, it does not explicitly say when to use this tool versus alternatives such as execute_command, nor does it mention any preconditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start an interactive terminal session. Then use session_read to see output, session_write to answer prompts, and session_stop to stop it.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory on the target device. Each command starts a fresh shell; use cwd for subsequent commands instead of relying on a previous cd. | |
| env | No | Environment overrides for this command, merged with the client environment. Values must be strings. | |
| command | Yes | Shell command | |
| client_id | No | Six lowercase letters or digits from list_clients. Required for multi-device tokens, even when only one device is online; optional for single-device tokens. | |
| timeout_ms | No | Execution timeout in milliseconds, up to 86400000 (24 hours). 0 disables the timeout. Default: 60000 for execute_command, 0 for session_start. | |
| client_token | Yes | Target client connection token (required when authenticated with the management key) |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. It reveals the multi-step interactive lifecycle, which is genuinely useful, but says nothing about session persistence on the server, whether sessions leak if not stopped, or what happens on timeout/error.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with zero filler; the core purpose is front-loaded and the sibling routing follows immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists and the input schema is fully described, so return values and parameters need no prose. The remaining gap is the missing contrast with execute_command, which matters given they are adjacent shell-execution siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and every parameter including cwd, env, timeout_ms, and client_token is documented in the schema itself. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Start an interactive terminal session'), and the follow-up sentence clarifies what the session object is for by naming session_read/write/stop. It does not clarify how this differs from the sibling execute_command, which is the main ambiguity an agent would face.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete workflow guidance: after starting, use session_read for output, session_write to answer prompts, session_stop to stop. Clear lifecycle context, but no explicit exclusion of when a one-shot execute_command would be preferable, so the decision point between the two is left implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop a running session.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | Session identifier | |
| client_token | Yes | Target client connection token (required when authenticated with the management key) |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full behavioral burden for a mutation tool. It does not disclose effects on the session, reversibility, authentication requirements, or idempotency, leaving key behavioral traits unknown.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is efficient and front-loaded, with no wasted words. However, for a mutation tool with no annotations, this brevity borders on under-specification rather than appropriate conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be described, and the schema fully documents both parameters. Still, the absence of annotations and any behavioral or usage context leaves the definition minimally complete for a session-terminating operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are documented in the schema. The description adds no parameter meaning beyond that baseline, which is acceptable given complete schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (Stop) and resource (session), and the verb distinguishes it from siblings like session_start and session_read. It lacks scope detail, but the core operation is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as session_read or session_write, nor on prerequisites. The schema hints at client_token conditions, but the description itself offers no routing context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send input to a running session. Include a newline to answer a prompt; input may be echoed in the terminal output.
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes | Input bytes as text, e.g. yes\n | |
| session_id | Yes | Session identifier | |
| client_token | Yes | Target client connection token (required when authenticated with the management key) |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses that input may be echoed in terminal output, so the agent isn't surprised by echo in session_read, but it says nothing about blocking behavior, error conditions, or the fact that writing to a live shell is an irreversible side effect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with zero padding; the core action comes first and the two practical caveats follow immediately. Every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need no explanation, and all three required parameters are documented in the schema. For a three-required-param mutation tool with no annotations, a note on failure or blocking behavior would round it out, but nothing critical is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that a newline answers a prompt, which clarifies why the input example ends with \n. The client_token auth condition is left entirely to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and target: send input to a running session, which cleanly separates it from session_read, session_start/stop, and execute_command. It doesn't name any sibling explicitly, so the differentiation is inferable rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Send input to a running session" implies the prerequisite that a session must already exist, and "Include a newline to answer a prompt" gives actionable usage for interactive prompts. However, no alternatives are named (e.g., when to prefer execute_command over writing to a session), and no when-not guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
create_clientexecute_commandlist_clientssession_readsession_startsession_stopsession_write
Add one secure layer between your agents and this server.