# Use BuildBase in Cursor

Add BuildBase's MCP server to Cursor in one click or in mcp.json, sign in as yourself, and manage your organization from Cursor's agent.

This page is part of **BuildBase in your AI tools**: it connects Cursor to BuildBase's own MCP server so you can manage your BuildBase organization from Cursor's agent. Cursor signs in as you and never sees your organization's secrets.

> **Note:**
  Want your own app to be agent-ready? See [Let your users connect Cursor to
  your app](/agents/clients/cursor), in **Agent-ready apps**.

## What you need

- Cursor.
- A BuildBase console account, whichever way you sign in to the console.
- An organization whose **AI agents** setting is not **Off** ([choose what agents may do](/console/ai-agents#choose-what-agents-may-do)). Agents can read by default.

## Add the server

**In one click:** use the Cursor button under [connect in one click](/console/ai-agents#connect-in-one-click), or open this link:

```text
cursor://anysphere.cursor-deeplink/mcp/install?name=buildbase-console&config=eyJ1cmwiOiJodHRwczovL2FwaS5jb25zb2xlLmJ1aWxkYmFzZS5hcHAvbWNwIn0%3D
```

**By hand:** add the entry to `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (one project):

```json
{
  "mcpServers": {
    "buildbase-console": {
      "url": "https://api.console.buildbase.app/mcp"
    }
  }
}
```

The link carries exactly this entry, base64-encoded.

## Sign in

Cursor registers itself with BuildBase as a public client, then opens BuildBase's sign-in page in your browser.

1. Sign in with your console account and your usual second step.
2. Read the consent screen: it names the client and the scopes it asks for, `console:read` and `console:write` to start. Approve it.

When a task needs more, such as an export or a delete, Cursor is told which scope is missing ([what an agent asks for](/console/ai-agents#what-an-agent-asks-for-at-sign-in)).

## What you see when you connect

Once you have signed in, BuildBase shows the consent screen in your browser. It names the tool, lists the scopes it asks for and the server the access is for, and changes nothing until you choose **Allow access**. Here it is for a tool that registered itself:

![BuildBase's consent screen for a tool that registered itself, here Example Agent: a warning that the app gave itself its name and nobody has checked it, what it may do as you, console:read and offline_access, the access to use at https://api.console.buildbase.app/mcp, and Allow access and Deny ringed](/images/console/ai-agents/hosted-consent.webp)

## Use it while you build

Ask Cursor's agent, for example:

- "Which environment variables does this Next.js app need for Acme? Fill `.env.example`, secrets left blank."
- "Create a feature flag `new-editor`, off, in staging, and gate the new editor on it here."
- "Write a blueprint for our roles and forms and show me the plan."

More, with what each one asks you to approve: [example prompts](/console/ai-agents#example-prompts).

## What differs in Cursor

- **The only tool with a one-click link besides VS Code.** The link adds the server; sign-in still happens in your browser.
- **Approval before each tool**, by default. Keep it for `console_write`, `console_destructive_change`, `create_org` and `blueprint_apply`.
- **Approvals of a change.** Where Cursor can ask you a question itself, the change BuildBase wants to make is shown to you and nothing happens unless you approve it. Otherwise it states the change and confirms it with a one-time code ([what stays with you](/console/ai-agents#what-stays-with-you)).
- **API keys.** For a job with nobody to sign in, an entry can send a header instead, such as `"headers": { "Authorization": "Bearer ${env:BUILDBASE_API_KEY}" }` ([connect with an API key](/console/ai-agents#connect-with-an-api-key)).

## If something goes wrong

| What you see                                        | Why                                                                     | What to do                                                                     |
| --------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| The link does nothing                               | Cursor is not installed, or the browser blocked the `cursor://` link    | Add the entry to `mcp.json` by hand                                            |
| The server shows an error                           | Sign-in did not finish                                                  | Open the Output panel (Cmd+Shift+U), pick **MCP Logs**, and sign in again      |
| Cursor says the organization does not let agents in | Its **AI agents** setting is **Off**, or your agent is blocked there    | An owner or admin changes it under **Security**, **AI agents**                 |
| Every change is refused                             | The organization is **Read only**, or you did not grant `console:write` | An owner or admin sets **Read and change**; approve `console:write` when asked |

To disconnect, remove the entry from `mcp.json` and [disconnect the agent](/console/ai-agents#disconnect-an-agent) in BuildBase, which ends its session at once.

## Related

- [BuildBase in your AI tools](/console/ai-agents): the server, its tools, and what stays with you.
- [Use BuildBase in VS Code](/console/ai-agents/vscode) and [Use BuildBase in Claude Code](/console/ai-agents/claude-code).
- [Let your users connect Cursor to your app](/agents/clients/cursor): the same client in **Agent-ready apps**.
- Cursor's own guide: [MCP in Cursor](https://cursor.com/docs/context/mcp).

## Frequently asked questions

### Is there a one-click install?

Yes. The Cursor button on the BuildBase in your AI tools page opens Cursor and adds the server; Cursor then asks you to sign in.

### Should the server go in the global or the project mcp.json?

~/.cursor/mcp.json makes BuildBase available in every project. .cursor/mcp.json adds it to one project and can be committed, and each teammate still signs in as themselves.

### Does Cursor ask before it runs a BuildBase tool?

Yes, by default Cursor asks for approval before each MCP tool call. Keep it on for the tools that change things.