How do you add an MCP server to Cursor?

Create or edit a .cursor/mcp.json file in your project root. Add an mcpServers object with a named entry that includes either a url field pointing to a remote HTTP MCP server or a command and args array for a locally-running server. Restart Cursor after creating the file so the editor picks up the new configuration. Once connected, your Cursor agent gains access to all the tools the MCP server exposes, discoverable through the tools/list handshake.

What is the difference between GitHub's official MCP server and AppHandoff's MCP server?

GitHub's official MCP server provides file-level access to repositories and requires Docker to run locally. It exposes tools for reading files, searching code, and managing issues and pull requests through the GitHub API. AppHandoff's MCP server is a hosted service that requires no Docker, carries coordination state such as handoff tickets, roles, milestones, and agent-published API contracts, and streams ticket updates in real time.

Why does my Cursor agent write code that calls the wrong API endpoints?

Cursor agents only see the files currently open in your editor and some nearby repository context. Without an MCP server providing project-level context, the agent guesses at API endpoints based on variable names, comments, and patterns it has seen in training data. Connecting an MCP server like AppHandoff gives the agent access to your actual API spec, so it writes code against real endpoint paths and response shapes rather than plausible guesses.

What Cursor agent capabilities does connecting an MCP server unlock?

Connecting an MCP server transforms your Cursor agent from a file-focused assistant into a project-aware collaborator. With AppHandoff's MCP server connected, the agent can read open tickets with implementation context, publish and confirm API contracts, check deploy readiness, and plan implementations based on real project state rather than just the file you have open.

How do I troubleshoot an MCP server not showing up in Cursor?

First confirm the .cursor/mcp.json file exists at your project root and contains valid JSON. Restart Cursor, since it reads the MCP config only on startup. If the server connects but shows no tools, reconnect once — the tool catalogue loads on session start. If you see authentication errors, re-authorize via OAuth: remove and re-add the server (or use the reconnect option) so the browser consent screen opens again.

GitHub MCP Server Setup in Cursor

TutorialMCPGitHubCursor

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 carries your project's coordination state (handoff tickets, roles, milestones, agent-published contracts, deploy checks) 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"
    }
  }
}

That's the entire config — no API key, no token to paste. Auth is OAuth 2.1: the first time Cursor connects, your browser opens the consent screen at portal.apphandoff.com/oauth/consent, you sign in and approve, and Cursor manages tokens from there. If you don't have an account 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. GitHub sync links tickets to their resolving pull requests — merged PRs auto-close the tickets they resolve.

Once connected, your Cursor agent has immediate access to 30+ 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()

"What contracts are published for this project?"
→ Agent calls: ask_apphandoff("show the published contracts")

"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, re-run the OAuth flow — remove and re-add the server (or use Cursor's reconnect option) so the browser sign-in opens again.

What Your Agent Can Do Now

With the GitHub MCP server connected, your Cursor agent can: read open tickets with role and milestone context, publish and confirm API contracts, check deploy readiness, and plan implementations based on real project state — 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 carries coordination state (tickets, roles, contracts — not just files), and it streams ticket updates in realtime via SSE. You can use both together — GitHub's server for file operations, AppHandoff for coordination context. See the full comparison on the GitHub MCP page.

Troubleshooting

Connection refused: Ensure the URL in mcp.json is exactly https://api.apphandoff.com/api/mcp-bot with no trailing slash. Authentication errors usually mean a stale OAuth token — reconnect the server so Cursor re-runs the browser sign-in.

Empty responses: Your project may not have any tickets or published contracts yet. File the first ticket (or ask the agent to) and the tools have real state to return.

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.