# Finch

> Finch turns a local HTTP or MCP service on your own machine into a secure public endpoint. The box dials out to the Finch hub, so nothing listens and no ports open. Auth is checked at the edge before a request reaches your box. Clients reach services at https://<slug>.finchmcp.com/<app_path>/ (MCP servers answer at /<app_path>/mcp) with an Authorization: Bearer finch_<key> header.

Finch is operated from a CLI. Every command is non-interactive and supports --json. If you are an AI agent driving Finch, install it and run `finch guide`: it prints a complete, self-contained operating manual.

Core loop: `finch login` (one-time approval — prints a link + code, you open the link on ANY device incl. your phone, so a headless box needs no local browser; over SSH use `finch login --headless` to skip the local browser spawn and flush the link straight to your terminal) → `finch add <app_path> --service http://127.0.0.1:<port>` → `finch run` → paste the printed URL into any MCP client with a key from `finch keys mint`. Fully unattended provisioning (no human): mint a one-shot ticket via `finch token` or the dashboard's "Add box", then `finch run --ticket -`.

## Base case: hello world, end to end

```bash
pip install fastmcp
cat > server.py <<'EOF'
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)
EOF
python server.py &                                   # serves MCP on http://127.0.0.1:8000

curl -fsSL https://finchmcp.com/install | sh         # install finch (macOS/Linux)
finch login                                          # prints a link + code; open on any device (phone ok) — no local browser needed
finch add hello --service http://127.0.0.1:8000      # writes finch.yml (no secrets)
finch run                                            # -> https://<slug>.finchmcp.com/hello/

# verify from another shell
finch test hello                                     # lists the greet tool
finch call hello greet --args '{"name": "world"}'    # -> Hello, world!

# give a client access
finch keys mint my-claude --service hello            # finch_ key, shown once
# MCP endpoint: https://<slug>.finchmcp.com/hello/mcp with Authorization: Bearer finch_...
```

## Docs

- [Quickstart](https://finchmcp.com/docs): install, log in, add a service, run, connect a client
- [AviaryMCP](https://finchmcp.com/docs/aviarymcp): public Python SDK release candidate on PyPI; one tool registry for MCP, REST, and OpenAPI with native Finch enrollment
- [Services & boxes](https://finchmcp.com/docs/services): the service/box model, finch.yml, states, enrolling more boxes
- [Keys & auth](https://finchmcp.com/docs/auth): finch_ keys, mint/list/revoke, the CLI admin token, how auth is checked at the edge
- [Access control](https://finchmcp.com/docs/acls): default-deny rules, granting by user, group, key, or tag; per-agent scoping
- [Domains](https://finchmcp.com/docs/domains): the automatic <slug>.finchmcp.com hub domain and custom hostnames
- [CLI reference](https://finchmcp.com/docs/cli): every command, grouped, with the finch.yml format

## Install

- [Install script](https://finchmcp.com/install): `curl -fsSL https://finchmcp.com/install | sh` (macOS and Linux)

## Optional

- [Dashboard](https://finchmcp.com/dashboard): services, boxes, keys, access rules, users, logs
- [Pricing](https://finchmcp.com/#pricing): free during beta; Hobby stays free for individuals and small groups

## AviaryMCP release candidate

AviaryMCP 0.1.0rc6 is public on PyPI (`python -m pip install 'aviary-mcp==0.1.0rc6'`) and is the preferred path for a new Python service. Read the [project-specific machine-readable guide](/aviarymcp-llms.txt) on this origin. It subclasses FastMCP and follows the normal FastMCP convention: create `mcp = AviaryMCP("My MCP Server")`, register tools with `@mcp.tool`, and call `mcp.run()`.

```python
from aviary_mcp import AviaryMCP, Finch

mcp = AviaryMCP(
    "calculator",
    finch=Finch.local(
        path="calculator",
        binary="/absolute/path/to/finch",
    ),
)

@mcp.tool
def add(a: int, b: int) -> int:
    return a + b

mcp.run()
```

AviaryMCP exposes the same registered tools at `/mcp`, `/api/v1/tools`, `/api/v1/tools/<tool>`, and `/api/v1/openapi.json`. Choose `Finch.local(...)` for an application-owned, zero-config Finch child or `Finch.agent(path=..., socket=/absolute/control.sock)` for an existing agent. Both modes register one exact route manifest and start browser device approval on first run. Do not duplicate an AviaryMCP-managed app path in `finch.yml`; keep YAML for existing or non-SDK services.