Does the agent need my SSH key?

No. TermCraft connects with the key from your Keychain. The agent never sees it.

Can other apps on my Mac reach the server?

Only with the access token. The server listens on 127.0.0.1 and rejects requests without it.

Connect Claude Code, Cursor or Codex to TermCraft

1. Turn on the MCP server

Open the settings, go to AI Agents and turn on agent access. The server listens on http://127.0.0.1:47823/mcp and only accepts requests with your access token. In the same place you can change the port or create a new token; agents with the old token lose access immediately.

TermCraft also shows these snippets with your real token filled in, ready to copy.

2. Add TermCraft to your agent

Claude Code

Run in a terminal:

claude mcp add --transport http termcraft http://127.0.0.1:47823/mcp --header "Authorization: Bearer <token>"

Cursor

Add to ~/.cursor/mcp.json under mcpServers:

"termcraft": {
  "url": "http://127.0.0.1:47823/mcp",
  "headers": { "Authorization": "Bearer <token>" }
}

VS Code

Add to .vscode/mcp.json. VS Code asks for the token on first start, so it does not end up in a file you might commit:

{
  "inputs": [
    { "type": "promptString", "id": "termcraft-token", "description": "TermCraft access token", "password": true }
  ],
  "servers": {
    "termcraft": {
      "type": "http",
      "url": "http://127.0.0.1:47823/mcp",
      "headers": { "Authorization": "Bearer ${input:termcraft-token}" }
    }
  }
}

Codex CLI

Add to ~/.codex/config.toml. Codex stops waiting for a tool after 60 seconds by default, and an approval can take up to two minutes, so the example raises the limit:

[mcp_servers.termcraft]
url = "http://127.0.0.1:47823/mcp"
http_headers = { "Authorization" = "Bearer <token>" }
tool_timeout_sec = 300

Claude Desktop

Add to claude_desktop_config.json under mcpServers (needs Node.js):

"termcraft": {
  "command": "npx",
  "args": ["-y", "mcp-remote", "http://127.0.0.1:47823/mcp", "--header", "Authorization: Bearer <token>"]
}

3. Choose what the agent may do

No Access: the agent does not see the host at all.
With Approval: the agent proposes commands, and you run or decline each one in the terminal of that host. You can allow one agent for 10 minutes.
Full Access: commands run without asking and are logged.

Production hosts and destructive commands always wait for your approval with Touch ID or your Mac password, whatever the level. ⌥⌘. pauses all agents at once.

What the agent can call

Tool	What it does
`list_hosts`, `get_host`	Hosts the agent may see, with address, environment and access level. Hosts set to no access do not appear.
`run_command`, `run_snippet`	Runs a command or a saved snippet over SSH and returns exit code, stdout and stderr. The agent passes a short reason that you see in the request.
`open_session`	Opens a terminal session in TermCraft for you to work in.
`list_snippets`, `list_groups`, `list_keys`	Read-only lists. Keys appear with name, type and fingerprint, never with the private part.
`create_host`, `update_host`, `delete_host`, `create_snippet`, `generate_key`	Changes to your library. By default each one waits for your approval.

What the agent never gets

Passwords, private keys, passphrases and the access token stay in the macOS Keychain. TermCraft opens the SSH connection itself, so the agent only sends a command and receives exit code, stdout and stderr (up to 256 KB per stream). Hosts set to no access, and jump hosts that are set to no access, stay hidden.

Connect your agent to TermCraft