AviaryMCP

AviaryMCP is a separate Python SDK for new MCP services. Define a tool once and get the MCP transport, typed REST endpoints and OpenAPI from the same registry. Run it on your machine like any other local app, then publish it with finch. You don't need it to use finch.

Public release candidate. Version 0.1.0rc6 is available on PyPI. Agents can read the hosted llms.txt and AviaryMCP's project llms.txt for the same guidance in machine-readable form.

When to use it

You haveUse
A new Python MCP service that should also speak RESTAviaryMCP, published with finch add.
An existing HTTP/MCP service, or another languageThe finch quickstart as is.
Several existing FastMCP serversMount them into one AviaryMCP parent, with a namespace for each child.

1. Install the release candidate

Pin the release candidate while evaluating it so a future prerelease does not change underneath your service.

python -m pip install 'aviary-mcp==0.1.0rc6'

2. Define the service

Save this as server.py:

from aviary_mcp import AviaryMCP

mcp = AviaryMCP("calculator")

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

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

By default AviaryMCP binds only to loopback, which is exactly what finch on the same machine needs. It serves MCP at /mcp, the REST API under /api/v1, and liveness at /birdz.

3. Publish it with finch

From here it is an ordinary finch service. With finch installed and logged in (see the quickstart), publish it with --forward-all, so the REST and OpenAPI paths are forwarded as well as /mcp:

python server.py &
finch add calculator --service http://127.0.0.1:8000 --forward-all
finch: added "calculator" → http://127.0.0.1:8000
       public URL: https://sunny-wren-42.finchmcp.com/calculator/mcp
finch service install

4. Use MCP or REST

The same add tool is available through each generated interface. Without --forward-all, only the MCP row works:

InterfacePath
MCP/calculator/mcp
Tool catalog/calculator/api/v1/tools
Call a tool/calculator/api/v1/tools/add
OpenAPI 3.1/calculator/api/v1/openapi.json
Liveness/calculator/birdz
finch test calculator
finch call calculator add --args '{"a": 20, "b": 22}'

curl -X POST \
  https://sunny-wren-42.finchmcp.com/calculator/api/v1/tools/add \
  -H 'Authorization: Bearer finch_...' \
  -H 'content-type: application/json' \
  -d '{"a": 20, "b": 22}'

A caller authenticates to finch with a finch_ key or OAuth. finch checks that credential and removes it before the request reaches your machine, so the service never sees the caller's key.

Compose existing FastMCP servers

from fastmcp import FastMCP
from aviary_mcp import AviaryMCP

weather = FastMCP("weather")

@weather.tool
def forecast(city: str) -> str:
    return f"sunny in {city}"

mcp = AviaryMCP("aviary")
mcp.mount(weather, namespace="weather")

The mounted tool becomes weather_forecast in MCP, REST, and OpenAPI. Namespaces keep tools from different servers from colliding.

← QuickstartServices & machines →