Build & publish an MCP app

git clone https://github.com/RecursionAI/axe.git
cd axe
uv sync --extra dev
uv run axe --help

axe new my-app                  # creates ./my-app (fails if the directory exists)
axe new my-app --python 3.12    # default; 3.11 or higher
cd my-app
cp .env.example .env.local      # fill APP_SUPABASE_* when you want DB tools
uv run fastapi dev

axe connect http://127.0.0.1:8000/mcp --no-oauth --name my-app
axe list
axe call hello

uv run fastapi deploy
fastapi cloud env set APP_SUPABASE_URL <url>
fastapi cloud env set APP_SUPABASE_SECRET_KEY <service-role-key>

# OAuth (default) — browser PKCE
axe connect https://example.com/mcp --name my-app

# Bearer token, skip OAuth
axe connect https://example.com/mcp --name my-app --no-oauth --token "$AXE_MCP_TOKEN"

axe apps                 # list registered apps (* = active)
axe select my-app        # switch active app and refresh tools

axe list                          # nested tool tree for the active app
axe describe enter_research       # schema + description
axe call check_in                 # LLM invents args from schema
axe call update_icp --args '{"industries":["Software"]}'

# Author cases (replaces prior cases for that tool)
axe generate enter_research
axe generate --app my-app --per-tool 5

# Run cases against the live MCP
axe test enter_research
axe test --app my-app
axe test --app my-app --all -v     # every configured agent + combined score

uvx fastapi-new myapp
cd myapp
uv add fastapi-mcp httpx

"""Save as app/mcp_store_auth.py

You do NOT implement OAuth. Forward Bearer → Store verify + advertise PRM.
Required env: APP_SLUG, STORE_URL
"""

from __future__ import annotations

import os
from dataclasses import dataclass
from uuid import UUID

import httpx
from fastapi import Depends, FastAPI, HTTPException, Request, status
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer

_bearer = HTTPBearer(auto_error=False)

APP_SLUG = os.environ["APP_SLUG"]
STORE_URL = (os.environ.get("STORE_BASE_URL") or os.environ["STORE_URL"]).rstrip("/")


@dataclass
class StoreUser:
    id: UUID
    email: str | None = None


def _prm_urls(request: Request, *, mcp_path: str = "/mcp") -> tuple[str, str]:
    base = str(request.base_url).rstrip("/")
    path = mcp_path if mcp_path.startswith("/") else f"/{mcp_path}"
    path = path.rstrip("/") or "/mcp"
    return f"{base}{path}", f"{base}/.well-known/oauth-protected-resource{path}"


def www_authenticate_headers(request: Request, *, mcp_path: str = "/mcp") -> dict[str, str]:
    _, metadata_url = _prm_urls(request, mcp_path=mcp_path)
    return {"WWW-Authenticate": f'Bearer resource_metadata="{metadata_url}"'}


def mount_protected_resource_metadata(app: FastAPI, *, mcp_path: str = "/mcp") -> None:
    path = mcp_path if mcp_path.startswith("/") else f"/{mcp_path}"
    path = path.rstrip("/") or "/mcp"

    def _metadata(request: Request) -> dict:
        resource, _ = _prm_urls(request, mcp_path=path)
        return {
            "resource": resource,
            "authorization_servers": [STORE_URL],
            "scopes_supported": ["mcp:use"],
            "bearer_methods_supported": ["header"],
            "resource_name": APP_SLUG,
        }

    @app.get("/.well-known/oauth-protected-resource", include_in_schema=False)
    def root_prm(request: Request) -> dict:
        return _metadata(request)

    @app.get(f"/.well-known/oauth-protected-resource{path}", include_in_schema=False)
    def path_prm(request: Request) -> dict:
        return _metadata(request)


async def verify_install(token: str) -> StoreUser:
    async with httpx.AsyncClient(timeout=10.0) as client:
        response = await client.get(
            f"{STORE_URL}/api/v1/auth/verify",
            params={"app": APP_SLUG},
            headers={"Authorization": f"Bearer {token}"},
        )
    if response.status_code == status.HTTP_401_UNAUTHORIZED:
        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid token.")
    if response.status_code != status.HTTP_200_OK:
        raise HTTPException(status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail="Store verify unavailable.")
    data = response.json()
    if not data.get("authorized"):
        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=data.get("reason", "not_installed"))
    return StoreUser(id=UUID(str(data["user_id"])), email=data.get("email"))


async def require_installed_user(
    request: Request,
    credentials: HTTPAuthorizationCredentials | None = Depends(_bearer),
) -> StoreUser:
    if credentials is None or credentials.scheme.lower() != "bearer":
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Missing bearer token.",
            headers=www_authenticate_headers(request),
        )
    try:
        return await verify_install(credentials.credentials)
    except HTTPException as exc:
        if exc.status_code == status.HTTP_401_UNAUTHORIZED:
            raise HTTPException(
                status_code=status.HTTP_401_UNAUTHORIZED,
                detail=exc.detail,
                headers=www_authenticate_headers(request),
            ) from exc
        raise

"""Save as app/mcp_transport.py — required for FastAPI Cloud production."""

from __future__ import annotations

import asyncio
import logging

from fastapi import APIRouter, FastAPI
from fastapi_mcp.server import FastApiMCP
from fastapi_mcp.transport.http import FastApiHttpSessionManager
from mcp.server.streamable_http_manager import StreamableHTTPSessionManager

logger = logging.getLogger(__name__)


class StatelessFastApiHttpSessionManager(FastApiHttpSessionManager):
    async def _ensure_session_manager_started(self) -> None:
        if self._manager_started:
            return

        async with self._startup_lock:
            if self._manager_started:
                return

            logger.info("Starting stateless StreamableHTTP session manager")
            self._session_manager = StreamableHTTPSessionManager(
                app=self.mcp_server,
                event_store=self.event_store,
                json_response=self.json_response,
                stateless=True,
                security_settings=self.security_settings,
            )

            async def run_session_manager():
                try:
                    async with self._session_manager.run():
                        logger.info("Stateless StreamableHTTP session manager is running")
                        await asyncio.Event().wait()
                except asyncio.CancelledError:
                    logger.info("Stateless StreamableHTTP session manager is shutting down")
                    raise
                except Exception:
                    logger.exception("Error in StreamableHTTP session manager")
                    raise

            self._manager_task = asyncio.create_task(run_session_manager())
            self._manager_started = True
            await asyncio.sleep(0.1)


def mount_stateless_http(
    mcp: FastApiMCP,
    router: FastAPI | APIRouter | None = None,
    mount_path: str = "/mcp",
) -> None:
    if not mount_path.startswith("/"):
        mount_path = f"/{mount_path}"
    if mount_path.endswith("/"):
        mount_path = mount_path[:-1]

    if router is None:
        router = mcp.fastapi

    assert isinstance(router, (FastAPI, APIRouter))

    http_transport = StatelessFastApiHttpSessionManager(mcp_server=mcp.server)
    dependencies = mcp._auth_config.dependencies if mcp._auth_config else None

    mcp._register_mcp_endpoints_http(router, http_transport, mount_path, dependencies)
    mcp._setup_auth()
    mcp._http_transport = http_transport

    if isinstance(router, APIRouter):
        mcp.fastapi.include_router(router)

    logger.info(f"MCP stateless HTTP server listening at {mount_path}")

import os

from fastapi import Depends, FastAPI
from fastapi_mcp import AuthConfig, FastApiMCP

from app.mcp_store_auth import StoreUser, mount_protected_resource_metadata, require_installed_user
from app.mcp_transport import mount_stateless_http

APP_SLUG = os.environ["APP_SLUG"]
STORE_URL = (os.environ.get("STORE_BASE_URL") or os.environ["STORE_URL"]).rstrip("/")

app = FastAPI(title="My App", version="0.1.0")
mount_protected_resource_metadata(app, mcp_path="/mcp")


@app.get("/health")
def health() -> dict[str, str]:
    return {"status": "ok", "app": APP_SLUG}


@app.get("/my_tool", operation_id="my_tool", summary="My first tool")
async def my_tool(user: StoreUser = Depends(require_installed_user)) -> dict[str, str]:
    return {"message": f"Hello {user.email or user.id}"}


mcp = FastApiMCP(
    app,
    name="My App",
    exclude_operations=["health_health_get"],
    auth_config=AuthConfig(
        issuer=STORE_URL,
        authorize_url=f"{STORE_URL}/authorize",
        oauth_metadata_url=f"{STORE_URL}/.well-known/oauth-authorization-server",
        client_id="mcp-store",
        client_secret="local-dev-secret",
        dependencies=[Depends(require_installed_user)],
        setup_proxies=True,
        setup_fake_dynamic_registration=False,
    ),
)
mount_stateless_http(mcp)  # → /mcp — do not use mcp.mount_http() in production

APP_SLUG=my-app
STORE_URL=http://localhost:8002

APP_SLUG=my-app
STORE_URL=https://mcp-store.fastapicloud.dev
APP_ENV=production

# Create .env.local in project root (see env vars section)
fastapi dev

# Health:  http://127.0.0.1:8000/health
# MCP:     http://127.0.0.1:8000/mcp

# Creates your FastAPI Cloud app on first run
fastapi deploy
# → https://myapp.fastapicloud.dev

# Set production env vars, then redeploy
fastapi cloud env set APP_SLUG my-app
fastapi cloud env set STORE_URL https://mcp-store.fastapicloud.dev
fastapi cloud env set APP_ENV production

fastapi deploy

# Catalog mcp_url:
# https://myapp.fastapicloud.dev/mcp

---
name: my-app
description: When and how agents should use this MCP app. Be specific.
---

# My App

## When to use

Describe the scenarios where an agent should reach for this app.

## Tools

### my_tool

What it does, required inputs, and example prompts.

### get_config_url (optional)

If you ship a secure config console for Courier (and similar hosts), document it here so clients can show the console chrome. Returns a short-lived `config_url` — never put the Store JWT in that URL.

## Setup

1. Install from the MCP Store catalog
2. Connect your MCP client to the app's MCP URL
3. Add this SKILL.md to your agent (Cursor skills folder)