Remote MCP

Remote MCP lets an external MCP client use one Caisey workspace: list devices, read chat transcripts, send prompts to the Caisey agent on a PC, and answer pending command approvals and operator questions through the same pipeline as the console for both Caisey 0.5 (OpenCode) and Caisey 1.0 runner permission and question cards.

This is security-sensitive. A connected client can send prompts that run tools on enrolled PCs. Command approvals and tool-risk analysis are not bypassed.

Server URL

Copy the streamable HTTP URL from Settings → Remote MCP while signed in. It is the console origin you used to sign in, plus /mcp. That page also lists connected clients and lets you revoke them.

The MCP server is on the console worker (/mcp), not a mcp. subdomain, so OAuth, Clerk, and device/session APIs stay on one origin. The hand-managed blog MCP at /mcp/blog is a different endpoint and still uses a separate blog token.

Use the URL for the Caisey environment you actually signed into. Do not point a client at production until that environment has been promoted.

GET /.well-known/mcp/server-card.json is the public server card for https://helpforsupport.com/mcp. That URL in the card stays on helpforsupport.com no matter which host serves the file.

What you get

After OAuth, the client can call:

• list_devices / get_device — status, runtime flavor (Caisey 0.5 OpenCode or Caisey 1.0 runner), online from stored heartbeat/sendability, last logged-in endpoint user (lastUser from caisey.endpointUser), and runner hostname when reported. list_devices accepts search (name/hostname) and lastUser (case-insensitive substring) and includes machineId in text. get_device also accepts hostname or a unique device name.
• list_sessions / read_transcript — paginated chat history for that workspace. list_sessions can filter by machine id, hostname, or unique device name.
• send_prompt — send text to the Caisey agent on a device; creates a session when needed; returns a Caisey session id and a live session card when the client supports MCP Apps. Commands go through the workspace approval policy; org, machine, or session allow rules may run matching tools without a prompt.
• watch_session / get_session_live — open or poll a one-line live status card (device, command, Running / Waiting on you / Done). Both include runState. While that state is awaiting approval, the live card shows Allow and Deny
• get_session_status / wait_for_messages — status reports running, awaiting approval, awaiting question, or idle, and inlines a pending approval or question. Wait caps at 25 seconds, returns the new text plus whether the turn is complete, and uses a message cursor so an appended part wakes the caller. Hosts that send a progress token can show wait progress
• list_pending_approvals / respond_to_approval — OpenCode and Caisey 1.0 runner approvals, using the same permission pipeline as the console, including org-role and per-user approval-scope caps. List rows include command text, device, session, requested-at, cached tool-risk, and the caller's allowed responses. list_pending_approvals renders the approval card with Allow and Deny; an empty list stays JSON
• list_pending_questions / answer_question — OpenCode and Caisey 1.0 runner operator questions, using the same submit path as the console. Answers are a map keyed by question id
• list_org_pending — every pending approval and question in the workspace in one call, with session id, machine id/hostname, command text, and risk summary

Clients that support MCP Apps or ChatGPT widgets can render ui://caisey/live-session, ui://caisey/approval-card, and ui://caisey/question-card. Other clients keep the JSON structuredContent fallback. See docs/remote-mcp.md for which hosts render inline cards.

Tokens are scoped to the signed-in user and the workspace chosen on the consent screen. Plan limits, billing gates, and token allowances still apply. There is no API-key shortcut.

Auth

Caisey implements OAuth 2.1 with authorization code, PKCE (S256), dynamic client registration, and hashed short-lived tokens. You sign in with Clerk on /oauth/consent, then pick one workspace. Do not paste Clerk session JWTs into MCP clients.

ChatGPT, Claude, Grok, and Cursor

Paste the MCP URL into a connector that supports streamable HTTP and OAuth. The client should discover .well-known metadata, register, and open Caisey sign-in. If a product asks for an API key, cancel. Revoke access later from Settings → Remote MCP.

Safety

MCP prompts are marked as MCP-origin in the audit trail. OpenCode and runner tool calls still hit command approval and risk analysis. Runner answers reuse the console permission-card path. Audit records include origin: mcp and the OAuth client name.