If you build apps with AI coding agents, you already know the hard part isn't writing code — it's keeping every agent on the same page. AppHandoff is the coordination layer for AI-built apps: shared project context, contract-aware scans, and a handoff workflow that travels between your tools. It speaks the Model Context Protocol (MCP), so the same MCP server plugs straight into Claude Code, Cursor, and Codex.
This walkthrough gets you connected and making your first call in about five minutes. No new accounts to wire up by hand, no SDKs to install — just one URL and an OAuth sign-in.
Prerequisites
You'll need an AppHandoff account with at least one project (see pricing to get started if you haven't yet), one of Claude Code, Cursor, or Codex — or any MCP-capable client — and a browser handy for the one-time OAuth consent screen.
A few facts make the rest of this simple. One endpoint for everyone: https://api.apphandoff.com/api/mcp-bot. There's no project_id baked into the config — the server resolves your project after you connect. Transport is Streamable HTTP, which modern MCP clients handle natively. Auth is OAuth 2.1: you sign in through your browser once and the client manages tokens after that. Static API keys are not accepted on the MCP endpoint — OAuth only.
Step 1 — Add the server to your client
Pick your tool. Each one points at the same URL. For Claude Code, run one command from your project directory:
claude mcp add apphandoff https://api.apphandoff.com/api/mcp-botFor Cursor, add it to .cursor/mcp.json in your project (create the file if it doesn't exist):
{
"mcpServers": {
"apphandoff": {
"url": "https://api.apphandoff.com/api/mcp-bot"
}
}
}For Codex (or any other MCP client), paste the URL into the client's MCP server settings. Most clients ask for a name and an HTTP/SSE-style URL — use the name apphandoff and the URL https://api.apphandoff.com/api/mcp-bot.
The exact config key for a remote HTTP MCP server varies by client and version. The pattern above — a named entry pointing at the URL — is what every current MCP client expects. If your client's settings use a different field name, map the URL into the HTTP/remote-server slot rather than the local/stdio command slot.
Step 2 — Complete the OAuth sign-in
The first time your client talks to AppHandoff, it kicks off the OAuth flow. Your browser opens to the consent screen at portal.apphandoff.com/oauth/consent. Sign in, approve access, and you're done — the client stores the token and refreshes it automatically.
A couple of things worth knowing. Tokens are short-lived (roughly 8 hours in production) and refresh silently in the background, so you shouldn't have to re-authorize during a normal working session. And if your client lets you set OAuth scopes manually, don't add offline_access — the auth backend rejects it and the consent screen won't render. Refresh tokens are issued automatically, so you don't need to ask for it.
Step 3 — Make your first call with ask_apphandoff
ask_apphandoff is the gateway tool. It's the friendliest way to verify the connection: instead of memorizing tool names, you ask in plain language and AppHandoff routes the request to the right underlying tool. In any of the three clients, prompt your agent with something like: Use the ask_apphandoff tool to give me a summary of my current project and any open handoff tickets.
If everything's wired up, the agent calls ask_apphandoff, AppHandoff resolves your project automatically (when you have exactly one, it auto-binds; with several, it'll ask you to pick), and you get back a real summary — project context plus whatever handoffs are open. That round-trip is your confirmation: the server is connected, authenticated, and seeing your data.
From here you can ask it to report a handoff, scan for contract mismatches, or check deploy readiness — all through the same gateway, all in plain English. Those tickets flow into a shared kanban that humans and bots read from the same board.
Troubleshooting
A few things trip people up, with quick fixes. "Tool was not found" or an empty tool list: the MCP server isn't connected or the tool list went stale (common right after a deploy). Disconnect and reconnect the AppHandoff server in your client, and double-check the URL is exactly https://api.apphandoff.com/api/mcp-bot — no typos, https, and the /api/mcp-bot path.
401 errors after a while: your access token expired and didn't refresh — reconnect the server to re-run OAuth, or restart the client to get a fresh session. Consent screen bounces with invalid_request: you (or your client config) requested offline_access; remove it, as covered in Step 2. Every project-scoped call fails but health checks pass: your project isn't registered or you don't have access — confirm the project first. Connection closed mid-call: a long request timed out or the transport dropped; retry, and reconnect if it persists.
You're connected
That's it — one URL, one sign-in, one call to ask_apphandoff. Your agents in Claude Code, Cursor, and Codex now share the same project context and the same handoff workflow, so work picked up in one tool lands cleanly in the next. Already building on Lovable? See the companion guide to setting up MCP with Lovable.