Quickstart

finch gives a server on your machine a stable https address. Your machine dials out to finch, so nothing on it listens and no ports open. This page starts from nothing: write a hello-world MCP server, then put it online and connect it to a client.

1. Write an MCP server

Any MCP server works. The fastest way to get one is FastMCP:

pip install fastmcp

Save this as server.py:

from fastmcp import FastMCP

mcp = FastMCP("hello")

@mcp.tool
def greet(name: str) -> str:
    """Say hello."""
    return f"Hello, {name}!"

if __name__ == "__main__":
    mcp.run(transport="http", port=8000)

Run it. It serves MCP over HTTP on your machine:

python server.py
Uvicorn running on http://127.0.0.1:8000

Already have a server? Skip to step 2. finch works with any local HTTP app; for a web app or a REST API, see web apps and REST.

2. Install finch

curl -fsSL https://finchmcp.com/install | sh

It runs on macOS and Linux and never asks for a password. Any machine that stays on and runs a shell can run finch: a laptop, a Mac mini, a Raspberry Pi, a VPS. Run finch on its own at any time to see every command.

3. Log in

finch login
  To finish login, open this page on any device (your phone or laptop
  is fine — you do NOT need a browser on this machine):

      https://finchmcp.com/cli?code=ZDTJ-9W63

  and confirm this code:  ZDTJ-9W63

  Waiting for approval  ✓
finch: logged in as you@example.com at https://finchmcp.com (saved to /Users/you/.finch/cli.json)

finch opens the sign-in page in your browser and waits. Sign in (or create a free account), check that the code matches, and approve it. You can also open the link on any other device: the machine you run this on doesn't need a browser or a screen. Over SSH, use finch login --headless, which skips the local browser and just prints the link.

This is the only step that needs you. Everything after it runs without prompts and takes --json, so an agent can do the rest (see agents.md).

4. Add the service

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

hello is the service name, and it becomes part of the URL. The first part, sunny-wren-42, is your account address (also called the slug): finch picks it for your account, and every service you publish lives under it. Callers need a key or a sign-in by default; see Access control.

finch add records the service in ~/.finch/finch.yml (or in ./finch.yml if the current directory has one). The file holds no secrets. To point the service at a different port later, run the same command again with the new URL.

5. Keep it running

finch service install
finch: installed /Users/you/Library/LaunchAgents/com.finchmcp.finch.plist (launchd) — serves /Users/you/.finch/finch.yml
       installed, running
       log: /Users/you/.finch/finch.log

This runs finch in the background, starts it when you log in and restarts it if it stops: a launchd agent on macOS, a systemd user service on Linux. It serves every service in finch.yml. Run it again after you add or change a service. To serve in the foreground instead, for a quick try, run finch run and leave the terminal open.

6. Test it

finch test hello
hello — 1 tool(s):
  • greet            Say hello.
finch call hello greet --args '{"name": "world"}'
Hello, world!

Both go out through finch and back to your machine, so a pass means the public address works end to end. If it fails, the message says which part didn't answer: finch, your machine, or your server.

7. Connect a client

finch connect hello --client claude-code   # or cursor, codex

finch connect makes a key for that one client and writes it into the client's settings, so you never copy a key by hand. Reload the client's MCP servers and greet is there.

For claude.ai or ChatGPT, add the public URL as a custom connector instead: they sign you in to finch in the browser, with no key. For any other client, make a key and paste it in as a bearer token:

finch keys mint my-client --service hello
# the finch_ key is shown once; put it in your client now

See what's happening

finch status          # this machine: login, services, background service
finch fleet           # every service on your account, its state and URL
finch logs hello      # recent calls: time, route, caller, status, duration

To take a service down, finch rm hello. To remove finch from this machine entirely, finch uninstall; the CLI reference lists what each one cleans up.

Where to next