# Use BuildBase in Zed

Add BuildBase's MCP server to Zed as a remote context server, sign in with OAuth as yourself, and manage your organization from Zed's agent panel.

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

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

## What you need

- Zed. Its MCP docs state no plan requirement.
- A BuildBase console account. Zed signs in on BuildBase's sign-in page with your console email address.
- An organization whose **AI agents** setting is not **Off** ([choose what agents may do](/console/ai-agents#choose-what-agents-may-do)).

## Add the server

1. Open **Settings** > **AI** > **MCP Servers**.
2. Choose **Add Server**, then **Add Remote Server**.
3. Enter `buildbase-console` and the URL `https://api.console.buildbase.app/mcp`, with no headers.

Or add it to your `settings.json` yourself, under `context_servers`:

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

There is no install link.

## Sign in

With no `Authorization` header in the entry, Zed runs the standard MCP OAuth sign-in and opens BuildBase's sign-in page. It registers its own client with BuildBase, so there is no client id to fill in.

1. Sign in with your console account and your usual second step.
2. Read the consent screen: it names the tool 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, Zed is told which scope is missing and the sign-in page opens again so you can approve just that one ([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 in the agent panel

Ask, for example:

- "Use buildbase-console to list my organizations and what agents may do in each."
- "Use buildbase-console to read the BuildBase docs on webhooks, then add a `user.created` handler to this app."
- "Use buildbase-console to show Acme's plans and what each one includes."

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

## What differs in Zed

- **Tool permissions.** `agent.tool_permissions.default` is `confirm` unless you change it, so Zed asks before every tool. To allow only BuildBase's reads, add per-tool keys such as `mcp:buildbase-console:list_orgs` and `mcp:buildbase-console:console_get`, and leave `console_write`, `console_destructive_change`, `create_org` and `blueprint_apply` on `confirm`. Never set the default to `allow` with BuildBase connected.
- **Approvals of a change.** Where Zed can ask you a question itself, the change BuildBase wants to make is shown to you and nothing happens unless you approve it. Otherwise the agent states the change and confirms it with a one-time code ([what stays with you](/console/ai-agents#what-stays-with-you)).
- **Errors in the reply.** When a BuildBase tool refuses something, Zed shows the server's message in the agent's reply, which says why and what to do.

## If something goes wrong

| What you see                                           | Why                                                                     | What to do                                                                                                            |
| ------------------------------------------------------ | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| No green dot next to the server                        | It has not connected, or sign-in did not finish                         | Hover the dot for its state, then remove and add the server again                                                     |
| Zed never opens the sign-in page                       | The entry has an `Authorization` header                                 | Remove `headers` from the entry, or use an API key on purpose ([API key](/console/ai-agents#connect-with-an-api-key)) |
| The agent 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**; then approve `console:write` when asked                                   |

To disconnect, remove the entry 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 Cursor](/console/ai-agents/cursor) and [Use BuildBase in Junie](/console/ai-agents/junie).
- [Let your users connect Zed to your app](/agents/clients/zed): the same client in **Agent-ready apps**.
- Zed's own guide: [Model Context Protocol](https://zed.dev/docs/ai/mcp).

## Frequently asked questions

### How does Zed know to sign me in?

When a remote server has no Authorization header in its entry, Zed runs the standard MCP OAuth sign-in. Leave the header out and Zed opens BuildBase's sign-in page.

### Can I allow BuildBase's read tools and confirm the rest?

Yes. Zed's tool permissions take per-tool keys in the form mcp:<server>:<tool>, so you can allow list_orgs or console_get and keep the change tools on confirm, the default.

### How do I check the server is running?

Open Settings, AI, MCP Servers. A green dot with the tooltip Server is active means Zed is connected.