Cursor supports MCP servers natively, which means your AI coding agent can access structured project data — API specs, database schemas, open tickets, and cross-repo contracts — directly from your editor. This guide walks through connecting a GitHub MCP server to Cursor, from creating the config file to making your first tool call.
What Is a GitHub MCP Server?
A GitHub MCP server exposes your GitHub project data through the Model Context Protocol. Instead of your AI agent only seeing the file you're editing, it gets structured access to your entire project: every API endpoint, every database table, every open ticket. GitHub offers its own official MCP server for basic repo access, but it requires Docker and only provides file-level context.
AppHandoff's MCP server goes further — it scans your GitHub repos on every push, extracts architecture-level data (API specs, DB schemas, frontend/backend contracts), detects mismatches, and streams ticket updates in realtime. No Docker required. One URL in your Cursor config.
Step 1: Create the MCP Config File
In your project root, create or edit .cursor/mcp.json. This file tells Cursor which MCP servers to connect to. You can have multiple servers — each provides different tools to your agent.
// .cursor/mcp.json
{
"mcpServers": {
"apphandoff": {
"url": "https://api.apphandoff.com/api/mcp-bot",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}Replace YOUR_API_KEY with your AppHandoff API key from the portal settings page. If you don't have one yet, sign up at apphandoff.com — the free tier includes one project.
Step 2: Connect Your GitHub Repos
In the AppHandoff portal, install the GitHub App on your org and select which repos to connect. Assign roles — mark your backend repo as 'Backend (target)' and your frontend repo as 'Frontend (source)'. The first scan runs automatically and extracts API specs, DB schemas, and usage patterns from both repos.
Once the scan completes, your Cursor agent has immediate access to 40+ MCP tools. No restart needed — the connection is live.
Step 3: Test the Connection
Open Cursor's composer (Cmd+I / Ctrl+I) and ask your agent to use the MCP tools. Try these prompts to verify everything is working:
# Ask your Cursor agent:
"What's the project summary for my AppHandoff project?"
→ Agent calls: get_project_summary()
"Show me all API endpoints in my backend"
→ Agent calls: get_api_spec()
"Are there any mismatches between frontend and backend?"
→ Agent calls: get_mismatches()
"What tickets should I work on next?"
→ Agent calls: get_my_workload()If the agent responds with structured data about your project, the connection is working. If you see authentication errors, double-check your API key in mcp.json.
What Your Agent Can Do Now
With the GitHub MCP server connected, your Cursor agent can: query your full API spec and DB schema, check for frontend/backend mismatches, read open tickets with architecture context, trigger rescans when you push changes, and plan implementations based on real project data — not just the file you have open.
The key difference from GitHub Copilot: Copilot sees your current file and nearby tabs. The MCP server sees your entire project architecture across repos. When your agent writes code using MCP context, it writes code that fits your actual API endpoints, matches your actual database schema, and implements what your actual tickets describe.
GitHub's Official MCP Server vs AppHandoff
GitHub's own MCP server (github.com/github/github-mcp-server) provides file-level access to repos — reading files, searching code, managing issues and PRs. It requires Docker to run locally and connects to GitHub's API directly.
AppHandoff's MCP server is different: it's a hosted service (no Docker), it scans repos to extract architecture metadata (not just files), it detects mismatches between frontend and backend, and it streams ticket updates in realtime via SSE. You can use both together — GitHub's server for file operations, AppHandoff for architecture context. See the full comparison on the GitHub MCP page (/github-mcp).
Troubleshooting
Connection refused: Ensure the URL in mcp.json is exactly https://api.apphandoff.com/api/mcp-bot with no trailing slash. Check that your API key is valid in the portal settings.
Empty responses: Your project may not have completed its first scan. Check the portal dashboard for scan status. If repos are connected but no scan has run, click 'Rescan' or push a commit to trigger one.
Tools not appearing: Restart Cursor after creating mcp.json. Cursor reads the MCP config on startup. If you edited the file while Cursor was running, a restart picks up the changes.