Quickstart

Finch turns a local service into a secure public endpoint. Your box dials out to the Finch hub, so nothing listens and no ports open. This page starts from zero: write a hello-world MCP server, then put it online.

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 localhost:

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

Already have a server? Skip to step 2. Finch fronts any local HTTP service, MCP or not.

2. Install Finch

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

Works on macOS and Linux. Anything that stays on and runs a shell can run Finch.

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… ✓ logged in as you@example.com

Finch prints a link and a code, then waits. Open the link on any device — the box you run this on doesn't need a browser or even a screen, so a headless server (a Mini, a Pi, a VPS) logs in fine: open the link on your phone, confirm the code, and the waiting box gets its credential. This is the only human step; every other command is non-interactive and supports --json. On a screenless box reached over SSH, use finch login --headless — same flow, but it skips the (pointless) local browser and flushes the link straight to your terminal.

Fully unattended (CI, imaging a fleet) with no human at all? Mint a one-shot ticket on a machine that's already logged in with finch token (or in the dashboard under Add box) and hand it to the new box: finch run --ticket -. For a single box you're setting up yourself, finch login from your phone is the easy path.

4. Add the service

finch add hello --service http://127.0.0.1:8000

This writes finch.yml next to your project. It holds no secrets, so you can commit it.

5. Run

finch run
✓ https://your-slug.finchmcp.com/hello/

Your server is now public, with auth checked at the edge. One finch run process serves every rule in finch.yml. An MCP server answers at /hello/mcp.

Check it end to end from another terminal:

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

6. Connect a client

Mint a key, then add the URL to any MCP client (Claude, Cursor, anything that speaks MCP) with the key as a bearer token:

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

Where to next