Documentation

API reference and MCP setup guides for AppHandoff.

Convert API (v2)

Single endpoint: source, target, and output. Use session cookie or API key (Bearer) + githubToken in body.

Loading API reference…

MCP Server Documentation

AppHandoff exposes a Model Context Protocol (MCP) server for Lovable and MCP-compatible clients. Use it to read backend endpoints, database context, design decisions, and project diagnostics.

1. MCP Endpoints

Use the strict endpoint for new bot installs:

  • https://apphandoff.com/api/mcp-bot (strict typed contract, recommended)
  • https://apphandoff.com/api/mcp (compatibility bridge for existing installs)
  • Call get_accessible_projects first, then pass project_id for project-scoped tools.

2. Authentication

MCP requests require authenticated access. In Lovable, add AppHandoff as an OAuth MCP server and complete authorization. Unauthenticated requests are rejected.

3. Core MCP Capabilities

  • Tools, resources, and prompts method families
  • API endpoint inventory, backend page context, and DB schema metadata
  • Frontend/backend mismatch diagnostics and project rules
  • Design decision publishing and ticket lifecycle (create/list/update/close)
  • Fly.io log retrieval via MCP tool calls

4. Testing MCP in the Dashboard

Go to your project page, open the MCP tab, and verify: connection status, endpoint/table counts, Lovable pages, mismatches, and design decisions.

5. Troubleshooting

  • If /api/mcp-bot fails for a client that still expects text envelopes, use /api/mcp temporarily.
  • For project-scoped tools, always pass project_id.
  • Always call get_accessible_projects first to select a valid project ID.
  • Run project rescan from dashboard if MCP data appears stale.

Getting Started

Install the GitHub App and connect your first Lovable project.

MCP Setup

Configure OAuth MCP connection and verify global endpoint + project_id usage.

Configuration

Customize output paths, protected files, and conversion rules.

Readiness Reports

Understand confidence scores, SSR blockers, and fix suggestions.