MCP server

The Model Context Protocol (MCP) server lets AI assistants like Claude operate your Telnety client over JSON-RPC 2.0. It exposes 11 tools across four safety tiers, scrubs secrets out of every response, rate-limits aggressive callers, and logs every operation for audit. The point is to make AI useful in a terminal without surrendering the keys to the kingdom.

Overview

Telnety's MCP server is a process that the desktop app spawns on demand. It listens on a local Unix domain socket (or named pipe on Windows) and speaks MCP version 2025-06-18. Any MCP-aware client — Claude Desktop, Claude Code, an in-house tool — connects to that socket, lists tools, and invokes them with structured arguments.

Configure the MCP server

Telnety publishes its MCP socket path on demand. Add the following block to your MCP client's configuration so the client knows how to find and trust it.

{
  "mcpServers": {
    "telnety": {
      "command":   "telnety",
      "args":      ["mcp", "stdio"],
      "transport": "stdio"
    }
  }
}

On first run, Telnety surfaces an in-app prompt asking you to grant the MCP server access. Decline and the MCP socket exits; accept and the socket stays open for the rest of the workspace session.

The 11 tools

The MCP server exposes 11 tools. Each tool has a strict input schema, a documented safety tier, and an audit log entry on every invocation.

• list_hosts (Tier 1) — return every saved host with metadata; never returns credentials.
• get_host (Tier 1) — return one host by ID with connection settings.
• list_sessions (Tier 1) — list active connection sessions with state and last activity.
• open_session (Tier 2) — open a session against a saved host; returns a session ID.
• close_session (Tier 2) — close an open session.
• read_session (Tier 1) — return the latest scrollback buffer for a session.
• run_command (Tier 3) — execute a shell command on a session and return the result with scrubbing applied.
• sftp_list (Tier 1) — list a remote directory.
• sftp_read (Tier 1) — return file contents up to 1 MiB; scrubbed.
• sftp_write (Tier 3) — write a file via SFTP; requires explicit user approval.
• vault_read (Tier 4) — read a secret from the vault; requires explicit approval and is the only tool that can return credentials.

Invocation example

// Request
{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "run_command",
    "arguments": {
      "session_id": "ses_001",
      "command":    "df -h"
    }
  }
}

// Response (after Tier 3 user approval)
{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Filesystem      Size  Used Avail Use% Mounted on\n/dev/sda1       100G   42G   58G  43% /\n"
      }
    ],
    "isError": false
  }
}

Safety tiers

Every tool has a safety tier. Tier behaviour is fixed: it determines the default approval policy and the audit-log retention window.

• Tier 1 — Safe. Read-only metadata. Auto-approved, logged for 30 days.
• Tier 2 — Moderate. Open/close sessions, allocate resources. One-shot approval per session by default; can be set to auto-approve per host.
• Tier 3 — Sensitive. Execute commands, write files. Per-call approval; last-minute review of the exact argument payload.
• Tier 4 — Critical. Read credentials. Always per-call approval; audit entry retained for 1 year minimum.

Output scrubbing

Before any tool response reaches the AI assistant, Telnety runs it through a scrubber that redacts well-known secret patterns:

• AWS access keys (AKIA*) and matching secret keys.
• GitHub personal access tokens (ghp_*, github_pat_*).
• PEM-armoured private keys (-----BEGIN [A-Z ]+ PRIVATE KEY-----).
• Bearer tokens in Authorization headers.
• Passwords inline in URLs (https://user:pw@host).

Scrubbed values are replaced with a deterministic token like [REDACTED:aws-access-key] so the model can still reason about the structure of the output without seeing the secret.

Rate limits

• 30 tool calls per minute, aggregated across all tools.
• 10 Tier 3+ calls per hour.
• 5 concurrent in-flight calls (semaphore).
• 50 KiB maximum argument payload, 1 MiB maximum response payload.

Audit logging

Every MCP call is logged to the local SQLite database with: timestamp, tool name, argument summary, session ID, safety tier, result code, exit code (for run_command), and elapsed time. Logs are queryable from Settings → Audit and exportable to JSON or CSV for compliance.