Skip to content
BuildBase

Let your users connect Cursor to your app

Give your users a one-click Cursor install link for your app's MCP server, the mcp.json entry behind it, and the redirect URLs Cursor signs in with.

This page is part of Agent-ready apps: it covers what you do so that your own users can connect Cursor to the app you built with BuildBase. Your app serves MCP with @buildbase/sdk, and each user signs in on your hosted sign-in page and approves Cursor as themselves.

Note

Want to manage BuildBase itself from your AI? See Use BuildBase in Cursor, in BuildBase in your AI tools.

The examples use https://app.example.com/api/mcp, the default path createAgentStack serves, and the name acme.

Before you share the URL

  1. Let Cursor get a client. Cursor registers itself as a public client: turn on Let agents register themselves, with a base client, in Set up agent access.

  2. Serve it on public HTTPS. The desktop app reaches any address the user's computer can; Cursor on the web and Cloud Agents sign in through a callback on cursor.com, so serve it publicly for those.

  3. Check it the way a client does:

    npx buildbase agent doctor --url https://app.example.com/api/mcp

Give your users a button

Cursor documents a one-click install link: the server's mcp.json entry as JSON, base64-encoded.

cursor://anysphere.cursor-deeplink/mcp/install?name=acme&config=eyJ1cmwiOiJodHRwczovL2FwcC5leGFtcGxlLmNvbS9hcGkvbWNwIn0%3D

npx buildbase agent install --url <mcp-url> prints this link for your server, and buildMcpInstallLinks() renders it as a button on your own docs page (connect an agent). Give the entry by hand beside the button, for users whose browser blocks the link:

{
  "mcpServers": {
    "acme": { "url": "https://app.example.com/api/mcp" }
  }
}

It goes in ~/.cursor/mcp.json for every project, or .cursor/mcp.json for one.

What your users see

  • Your sign-in page in their browser, with your branding and sign-in methods.
  • Your consent screen, naming the client and the scopes it asks for. A self-registered agent chooses its own name, so it is shown as unverified.
  • An approval before each tool call, by default. Mark read tools readOnlyHint: true and changes destructiveHint as they are.

When Cursor connects, your user approves it on your consent screen. Here it is for an agent that registered itself:

Your app's consent screen for an agent that registered itself, here Notes Helper: a warning that the app gave itself its name and nobody has checked it, what it may do as the person, the permissions it asked for by name, and Allow access and Deny ringed

If something goes wrong

What your user seesWhyWhat to do
The link does nothingCursor is not installed, or the browser blocked cursor://Add the entry to mcp.json by hand
The server shows an errorSign-in failedOutput panel (Cmd+Shift+U) > MCP Logs shows why
Sign-in fails before your page opensSelf-registration is off, or no base clientTurn it on with a base client in agent access
Cloud Agents cannot reach the serverThe endpoint is not public HTTPSServe it on public HTTPS
Cursor sees fewer tools than you definedTools that need a scope the token lacks are hiddenAsk for the scope at sign-in, or drop requiredScopes from the tool

Related

Frequently asked questions

How do I build the install link for my URL?
Base64-encode the server's mcp.json entry, here {"url":"https://app.example.com/api/mcp"}, and pass it as config with the name in a cursor://anysphere.cursor-deeplink/mcp/install link. npx buildbase agent install prints it for your server.
Which redirect URLs does Cursor sign in with?
http://localhost:8787/callback in the desktop app, and https://www.cursor.com/agents/mcp/oauth/callback on the web and in Cloud Agents. A self-registered client brings them, so you add nothing by hand.
Can my users connect without a browser sign-in?
An entry can send headers, but for a person OAuth is the way. Never ask a user to paste a token into a file.