agentmount

agentmount

Make a FastAPI app agent-ready with clear, safe defaults.

agentmount turns selected FastAPI routes into agent-callable tools and exposes:

• an agent manifest at /.well-known/agent.json
• an OpenAI-compatible tool list at /.well-known/openai-tools.json
• an MCP endpoint at /mcp

The core design choice is internal ASGI loopback dispatch, so agent calls flow through your existing FastAPI stack (middleware, auth, validation, logging, error handlers) instead of bypassing it.

Current status

This repository is ready for the 1.0.0 release cut.

Implemented now:

• project foundation, packaging, lint/type/test setup
• decorator metadata model with rate limit syntax validation
• in-memory registry with duplicate detection
• scanner that converts FastAPI routes into ToolSpec records with skip reasons
• enable_agents wiring and state container
• manifest and OpenAI tools endpoints
• MCP transport with tools/list and tools/call via ASGI loopback
• runtime rate limiting and audit logging
• inspect CLI (python -m agentmount inspect <module>:<app>)
• end-to-end and unit tests across core, transports, scanner, registry, and CLI

Release status:

• lint, type-checking, tests, and local artifact builds are passing
• tutorial and runnable example app are complete
• remaining release work is external: tag, publish, and announce

For milestone details, see ROADMAP.md.

For a runnable end-to-end example, start with docs/tutorial.md and examples/shop/README.md.

Why agentmount

Typical approaches to agent integration are either brittle or framework-specific wrappers. agentmount aims to be:

• FastAPI-native
• MCP-first
• explicit and opt-in by default
• easy to adopt incrementally

Design principles

• Safe defaults: only explicitly exposed routes are agent-callable by default.
• Keep framework behavior: route execution goes through FastAPI, not a custom mini-framework.
• Deterministic outputs: scanner and manifests are stable and testable.
• Small public API: prefer a single clear entry point.

Planned public usage

from fastapi import FastAPI
from agentmount import enable_agents, agent_tool

app = FastAPI()

@app.post("/cart/items")
@agent_tool(description="Add a product to the cart", rate_limit="10/min")
def add_to_cart(item: dict) -> dict:
    return {"ok": True}

enable_agents(app)

Notes:

• enable_agents is fully implemented and mounts all discovery/transport endpoints.
• The scanner, decorator, registry, transports, and runtime controls are implemented and tested.

You can inspect any app locally before starting a server:

python -m agentmount inspect examples.shop.app:app

Exposure model (v1)

Scanner supports three exposure modes:

• decorated: only routes marked with @agent_tool() are included
• tagged: routes with a specific FastAPI tag are included (plus decorated overrides)
• all: all supported HTTP routes are included

Unsupported route shapes are not silently accepted; they are returned as skipped with explicit reasons (for example UploadFile, websocket routes, streaming responses, Depends, and BackgroundTasks in current scanner scope).

Architecture at a glance

Agent client
   -> /mcp, /.well-known/agent.json, /.well-known/openai-tools.json
   -> agentmount transport layer
   -> ASGI loopback dispatch (httpx ASGITransport)
   -> existing FastAPI app middleware + route handler

See docs/architecture.md for the full rationale and locked decisions.

MCP security boundary

For tools/call, agentmount forwards only the Authorization header from the incoming MCP request into loopback tool execution.

• Authorization is forwarded so existing FastAPI auth dependencies continue to work.
• Other inbound headers are intentionally dropped to reduce header-injection risk across the MCP boundary.

Development quickstart

Requirements

• Python 3.11+

Setup

pip install -e .[dev]

or with uv:

uv sync --all-extras

Run checks

ruff check .
ruff format --check .
mypy src
pytest -q

Pre-commit

pre-commit install
pre-commit run --all-files

Test status (implemented slices)

• tests/test_smoke.py
• tests/test_decorators.py
• tests/test_registry.py
• tests/test_scanner.py
• tests/test_core.py
• tests/test_manifest.py
• tests/test_openai_tools.py
• tests/test_mcp.py
• tests/test_ratelimit.py
• tests/test_audit.py
• tests/test_inspect_cli.py

These are currently passing in local full-suite runs.

Repository structure

src/agentmount/
  core.py            public entry point (enable_agents)
  decorators.py      @agent_tool metadata decorator
  registry.py        in-memory ToolSpec registry
  scanner.py         FastAPI route scanning and filtering
  schema.py          ToolSpec and schema builders
  ratelimit.py       runtime limiter
  audit.py           audit logging
  transports/        manifest, OpenAI tools, MCP mounts
  __main__.py        inspect CLI
  _internal/         internal dispatch helpers

tests/
  scanner/decorator/registry/core/transports/ratelimit/audit/cli coverage

docs/
  architecture and manifest spec

Documentation

• Architecture: docs/architecture.md
• Manifest spec: docs/agent-json-spec.md
• Roadmap: ROADMAP.md
• Contributing: CONTRIBUTING.md

Road to 1.0

The 1.0 scope is intentionally narrow:

• FastAPI only
• MCP + manifest + OpenAI tool export
• rate limiting + audit logging
• inspect CLI

Out of scope for 1.0 includes approval flows, auth provider modules, websocket/file tool support, and hosted control planes.

Contributing

Issues and PRs are welcome. Please read CONTRIBUTING.md before opening a PR, and keep changes aligned with docs/architecture.md.

License

Apache-2.0. See LICENSE.