Autonomous MCP
← Home
InstallPairConnect ChatGPT ToolsConfigurationSafety Troubleshooting

Install the agent

Run this on the machine you want ChatGPT to reach. Node 20.11 or newer.

npm install -g autonomous-mcp

Check it is there:

autonomous-mcp --version

Pair the machine

Open your dashboard, press Generate pairing code, then run this on the machine. The code lasts 10 minutes and works once.

autonomous-mcp pair YOUR-CODE

Then start the agent. Leave it running. It keeps one outbound connection open and reconnects on its own.

AUTONOMOUS_ALLOWED_DIRS=$HOME/projects autonomous-mcp

Other commands

  • autonomous-mcp status shows the backend, device name and allowed folders
  • autonomous-mcp unpair forgets the stored credential

Connect ChatGPT

You need ChatGPT Plus, Pro, Business, Enterprise or Edu. The free tier cannot add connectors.

  • In ChatGPT, open Settings → Connectors → Add custom connector.
  • Paste this URL and choose OAuth:
https://mcp.octamundi.com/mcp
  • ChatGPT sends you here to sign in and approve. After that it can list the tools.
  • Turn on Developer Mode in ChatGPT settings to enable every tool. Without it, only search and fetch are used.

Revoke the connection any time from your dashboard under Connected apps.

Tools

Every tool runs on a paired machine unless noted. With more than one machine online, pass deviceId to say which; with exactly one, it is chosen for you.

Finding things

search fetch start_search get_more_search_results stop_search list_searches

Files

read_file read_multiple_files write_file write_pdf edit_block list_directory create_directory move_file get_file_info

Processes

start_process read_process_output interact_with_process force_terminate list_sessions list_processes kill_process

Your account

who_am_i list_devices get_usage_stats get_recent_tool_calls ping

Agent settings

get_config set_config_value

Configuration

Set these in the environment where the agent runs.

VariableDefaultWhat it does
AUTONOMOUS_ALLOWED_DIRSempty Colon-separated folders the agent may touch. Empty means the whole filesystem, so set this.
AUTONOMOUS_BACKEND_URLthis server Backend address.
AUTONOMOUS_DEVICE_IDhostname How this machine is named in your dashboard.
AUTONOMOUS_CONFIG_DIR~/.autonomous-mcp Where settings and the device credential are kept.
AUTONOMOUS_TOOL_TIMEOUT_MS600000 How long a single tool call may run.

What the agent can and cannot do

  • Folders. With AUTONOMOUS_ALLOWED_DIRS set, every path is resolved to its real location first, so a symlink cannot lead outside the list.
  • Commands. Destructive commands are refused before they run, including when hidden behind &&, ;, a pipe, a subshell or $(...). This is a guard, not a sandbox: an allowed command can still do real work.
  • Network. The agent only connects outward. Nothing on your machine listens for inbound connections.
  • Writes. Replacing a file that already has content requires saying so explicitly, so an accidental write cannot silently destroy it.
  • Credentials. The device credential is stored with owner-only permissions. Your API key and password are kept only as hashes.

Troubleshooting

ChatGPT says it cannot reach any machine

The agent is not running, or not paired. Run autonomous-mcp status on that machine.

"Path not allowed"

The path is outside AUTONOMOUS_ALLOWED_DIRS. Add the folder and restart the agent.

"Blocked command"

Something in the command line is on the denylist. It is refused even inside a chain or a substitution.

Several machines are online

Ask ChatGPT to use a specific machine by name, or unpair the ones you are not using.

Register failed after reinstalling

The stored credential was revoked. Run autonomous-mcp unpair and pair again with a new code.