MCP

Odyshell exposes a remote MCP adapter over its canonical Agent HTTP interface. The adapter does not own authorization logic: OAuth identity, Organization isolation, policy, Session expiry, idempotency, Command bounds, and audit are enforced by the same Server modules used by HTTP.

There is no local stdio MCP transport in the CLI.

Connect

Configure the Server with Odyshell Identity OAuth, then add its MCP resource to your client:

https://mcp.example.com/mcp

The client opens Odyshell Identity in the browser. Sign in, select the Organization, and approve the installation. Authorization Code with PKCE binds the resulting Agent identity to that Organization. Revoking the installation prevents later access; membership in another Organization does not cross that isolation boundary.

Tools

The remote adapter exposes only the agent-native workflow:

1. machines_list lists online Windows, Linux, and macOS Machines available to the authenticated Agent under Local Policy.
2. session_request asks for temporary shell authority on exactly one Machine. It returns a Session that is opening, pending human approval, or denied.
3. session_get reads the durable Session state after approval, reconnect, cancellation, or expiry.
4. command_run starts one asynchronous non-interactive shell Command inside an active Session.
5. command_get reads Command state and bounded output byte counts.
6. command_output reads transient base64 stdout/stderr chunks after a sequence cursor.
7. command_cancel requests process-tree termination for an active Command.
8. session_complete closes authority after every Command is terminal.
9. session_cancel cancels active Commands and closes Session authority.

Read-only tools are annotated as read-only. Mutations declare their destructive and idempotent behavior so MCP hosts can apply their own supervision without changing Server authorization.

Request and run work

Call machines_list before selecting a target. Generate a UUIDv4 idempotency key for each logical session_request; reuse it only to retry the exact same input. If the Session is pending approval, poll session_get instead of creating another Session.

Once the Session is active, call command_run with:

• the Session ID;
• the complete shell command as text;
• an optional absolute working directory;
• an optional bounded timeout;
• a fresh UUIDv4 idempotency key for that logical Command.

Commands do not accept caller-provided environment variables or standard input. The shell runs as the operating-system user configured by the Machine's Client Profile, without a PTY or persistent shell process. That authority can read secrets and change services available to the same user.

Poll command_get until the Command is terminal. Read output incrementally with command_output, passing the last sequence cursor as after. Output is transient and may be truncated at the Local Policy byte ceiling; durable audit stores the exact command and metadata, not stdout or stderr.

After all work is terminal, call session_complete. Use command_cancel for one active process or session_cancel to close the whole authority window. Calls are safe to repeat with the documented resource identity, and reconnecting clients resume by reading existing Session and Command IDs.

Human supervision

A Session requested by an Operator Agent can open without a person. A Session requested by a Standard Agent waits in the dashboard until an Owner, Admin, or Supervisor approves or denies it. Approval never widens the Machine's Local Policy. If the Machine is offline after approval, authority delivery remains pending and resumes only when the authenticated Client reconnects.

MCP host safety controls run before a tool call reaches Odyshell. If a host blocks a call and no Session or Command appears in Odyshell, change the host policy; Odyshell does not weaken tool annotations to bypass it.