Services & machines

A service is a local app you publish with finch. A machine is a computer running finch that serves it. This page covers how the two fit together, what lives in finch.yml, and how to change, remove and update things later.

The model

A service is a local HTTP app: usually an MCP server, but a web app or a REST API works too. finch publishes it at https://<account address>.finchmcp.com/<name>/. Your account address (the slug, such as sunny-wren-42) is picked by finch for your account; the name is what you pass to finch add.

A machine is any Mac or Linux computer running finch. It dials out to finch, so nothing on it listens and no ports open. One finch process on a machine serves every service in its finch.yml.

Adding a service

Start your app locally first, then:

finch add printer --service http://127.0.0.1:8000
finch: added "printer" → http://127.0.0.1:8000
       public URL: https://sunny-wren-42.finchmcp.com/printer/mcp
finch service install
finch test printer

finch add records the service in finch.yml and prints its public URL (the url field with --json). finch.yml holds no secrets; each service's credential is saved separately under ~/.finch/.

The name becomes part of the URL, and finch normalizes it first: it lowercases it and turns each run of anything that isn't a letter or digit into one -. finch add My_API.v1 … publishes my-api-v1 (at …/my-api-v1/mcp) and prints a note saying so; use that name in every later command. A name you type can be up to 63 characters of letters, digits, -, _ and . (the last three only between letters or digits), so names like notes or team-wiki are kept exactly as typed. If your account already has a service by that name that no machine publishes, the new one is published as printer-2, and finch add says so; if another machine publishes it, finch add stops and asks for another name.

By default callers need a finch_ key or an OAuth sign-in. Add --public to let anyone with the URL in; finch auth printer key closes it again.

Changing a service's port

On the machine that publishes it, run finch add again with the same name and the new URL. finch updates that service's entry in finch.yml instead of adding a second service, and the public URL stays the same. If the background service is running, finch add restarts it so the change takes effect; if not, the next finch service install (or finch run) picks it up.

finch add printer --service http://127.0.0.1:9000
finch: updated "printer" → http://127.0.0.1:9000 (was http://127.0.0.1:8000)
       public URL: https://sunny-wren-42.finchmcp.com/printer/mcp
       restarted the background service to apply it

Web apps and REST APIs

By default finch forwards only the MCP endpoint: /printer/mcp reaches /mcp on your app, and every other path is refused. That keeps the rest of your local app private. For a web app, a REST API or a public page, add --forward-all so every path under the service is forwarded:

finch add demo --service http://127.0.0.1:3000 --public --forward-all
# https://sunny-wren-42.finchmcp.com/demo/about → http://127.0.0.1:3000/about

The app is served under /demo/, so links and assets in it should use relative paths (or know their base path). Streamed responses pass through as they are written.

Running in the background

finch run serves in the foreground and stops when the terminal closes. To keep your services up across logouts and reboots, install finch as a background service:

finch service install      # launchd on macOS, systemd --user on Linux
finch service status       # installed? running?
finch service uninstall    # stop and remove it

On macOS this writes a LaunchAgent at ~/Library/LaunchAgents/com.finchmcp.finch.plist and logs to ~/.finch/finch.log (moved to finch.log.1 when a start finds it over 10 MiB). On Linux it writes a systemd user unit, finch.service; read its log with journalctl --user -u finch.service. Either way it needs no root, starts at login, restarts finch if it exits, and serves the finch.yml that finch add wrote.

Running install again is safe, and it is how you apply a change to finch.yml: it restarts the service. Stop any finch run you started in a terminal first, since only one finch per machine can serve. install waits about 20 seconds for every service to connect, and if one doesn't, it exits with an error that says why when it knows.

finch.yml

finch add writes this file for you, at ~/.finch/finch.yml unless the current directory already has a finch.yml.

hub: https://finchmcp.com
box: studio                          # this machine's name
ingress:
  - app_path: printer                # the service name: sunny-wren-42.finchmcp.com/printer/
    service: http://127.0.0.1:8000   # where the app runs on this machine
  - app_path: demo
    service: http://127.0.0.1:3000
    forward_all: true                # forward every path, not just /mcp

hub is where the machine connects. box names this machine (it defaults to the hostname). Each ingress entry is one service: its name (app_path), the local URL it forwards to (service), and optionally forward_all.

Several services on one machine

Run finch add once per service, then finch service install once to serve them all:

finch add printer --service http://127.0.0.1:8000
finch add scraper --service http://127.0.0.1:8001
finch service install

Removing a service

finch rm printer

This removes the service from your account, deletes its entry from finch.yml and deletes its credential on this machine. Its public URL stops answering. If finch runs in the background, finch rm restarts it without the removed service; if that was the machine's last service, it says to run finch service uninstall instead. Keys scoped to that service stay on your account until you revoke them, and would work again if you re-add the same name; list and revoke them with finch keys list and finch keys revoke.

To take finch off a machine altogether, run finch uninstall. See Remove finch for exactly what it cleans up.

States

finch fleet lists every service on your account with its state and public URL:

When something is down

If a machine loses its connection, its services show as offline. Nothing is deleted and nothing needs reinstalling: finch reconnects on its own. While a service is offline, callers get a 503, but a client that hasn't signed in yet still gets the sign-in challenge, so a claude.ai or ChatGPT connector can finish setting up and work once the machine is back.

If the machine is connected but your app isn't running, callers get a 502 that names the service and never shows the local address:

{"error":"finch reached the machine, but the local service isn't answering","service":"printer"}

Start the app, then check it with finch test printer. finch logs printer shows the recent calls and their status.

Keeping finch up to date

finch update
finch 1.8.0 is already the latest

When a newer version exists, finch update downloads it, swaps the binary in place and restarts the background service on it. When you already have the latest, it says so and changes nothing; --force reinstalls anyway. A failed download never touches the binary you are running.

Adding another machine

Only your first machine needs the browser step. From a machine that is already logged in, finch token makes a fresh login you can pipe to another one:

finch token | ssh you@pi "finch login --token -"
ssh you@pi "finch add sensors --service http://127.0.0.1:9000 && finch service install"

Checking on things

finch status --json     # this machine: logged in? what does finch.yml serve? URLs
finch fleet --json      # every service on the account, its state and URL
finch logs printer      # recent calls to one service

See the CLI reference for every command and its JSON output.