# Connect an AI agent to your app

Add the MCP server of an app built on BuildBase to Claude, ChatGPT, Cursor, VS Code and other agent clients, check it first, and list it on the MCP Registry.

Once your app serves MCP with @buildbase/sdk ([MCP and agents](/reference/mcp-agents)), any MCP client can connect to its endpoint. The examples on this page use `https://app.example.com/api/mcp`, the default path `createAgentStack` serves, and the name `acme`. Your users never paste a key: the agent opens your hosted sign-in page, the person signs in and approves it on the consent screen, and the agent acts as that person and can never do more than they can.

## Before you share the URL

1. **Serve it on public HTTPS.** Claude and ChatGPT connect from their own servers, so a server on `localhost`, a private network or behind a VPN is out of their reach.
2. **Let agents register themselves.** Claude, ChatGPT and most clients register their own client the first time they connect. Turn on **Let agents register themselves** and pick a base client in [Set up agent access](/sign-in-setup/agent-access); until then, those clients cannot sign in.
3. **Check it the way a client does.** From `@buildbase/sdk` 1.0.0, the doctor walks the first contact an agent makes: the 401 challenge, the protected-resource and authorization server metadata, redirects, latency, a stable tool list, and a lint of every tool against the Claude and ChatGPT directory rules. It exits `1` when a check fails.

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

Set `BUILDBASE_DOCTOR_TOKEN` to a token for your server to run the tool checks as well. The token is read from the environment, never from a flag.

## Claude

### Claude and Claude Desktop

A remote server is added to your Claude account as a custom connector, and it then works on claude.ai and in Claude Desktop:

1. Go to **Customize** > **Connectors**.
2. Choose **+ Add**, then **Add custom connector**.
3. Enter a name, paste `https://app.example.com/api/mcp` and choose **Continue**.
4. Under **Authentication**, choose **Sign in when needed** (or **Sign in now**). Under **OAuth client**, choose **Register automatically**, which uses the self-registration you turned on above.
5. Choose **Add**. In a chat, turn the connector on from **+** > **Connectors**.

Custom connectors are on every Claude plan; on Team and Enterprise an owner adds them under **Organization settings** > **Connectors** and members then choose **Connect**.

### Claude Code

```bash
claude mcp add --transport http acme https://app.example.com/api/mcp
```

Then run `/mcp` inside Claude Code and sign in in the browser it opens. Add `--scope project` to write the server to `.mcp.json` and share it with everyone on the project.

## ChatGPT

1. Open **Plugins**, choose the **+** button, then **Add custom MCP server**.
2. Enter a name and, under **Connection**, `https://app.example.com/api/mcp`.
3. Choose **OAuth** for authentication, review the warning, then create it and sign in.

ChatGPT connects to public HTTPS servers only, on the web. Custom MCP servers are for ChatGPT Business, Enterprise and Edu; on a workspace, an admin may need to allow them first. ChatGPT's deep research and company knowledge call two read-only tools named `search` and `fetch`: `defineSearchFetchTools` in [MCP and agents](/reference/mcp-agents) gives your app both.

## Cursor

Add the server to `.cursor/mcp.json` in a project, or to `~/.cursor/mcp.json` for every project:

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

Or give your users a one-click link. The `config` is the server's entry, as JSON, base64-encoded:

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

## VS Code

Add it to `.vscode/mcp.json` (VS Code uses `servers`, not `mcpServers`):

```json
{
  "servers": {
    "acme": { "type": "http", "url": "https://app.example.com/api/mcp" }
  }
}
```

From a terminal:

```bash
code --add-mcp '{"name":"acme","type":"http","url":"https://app.example.com/api/mcp"}'
```

Or as a link, with the same JSON URL-encoded (VS Code Insiders uses `vscode-insiders:`):

```text
vscode:mcp/install?%7B%22name%22%3A%22acme%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapp.example.com%2Fapi%2Fmcp%22%7D
```

## Devin Desktop (formerly Windsurf)

Add it to `mcp_config.json` (`~/.config/devin/mcp_config.json` on macOS and Linux, `%APPDATA%\devin\mcp_config.json` on Windows). It signs in with OAuth:

```json
{
  "mcpServers": {
    "acme": { "serverUrl": "https://app.example.com/api/mcp" }
  }
}
```

## Goose

Run `goose configure`, choose to add an extension, pick **Remote Extension (Streamable HTTP)**, and enter `acme` and `https://app.example.com/api/mcp`. In Goose Desktop: **Settings** > **Extensions** > **Add custom extension**, with the Streamable HTTP type.

## Gemini CLI

```bash
gemini mcp add --transport http acme https://app.example.com/api/mcp
```

Or in `settings.json`, with `httpUrl` (Gemini CLI's `url` field means the older SSE transport):

```json
{
  "mcpServers": {
    "acme": { "httpUrl": "https://app.example.com/api/mcp" }
  }
}
```

Gemini CLI finds your sign-in from the 401 challenge and runs it in a browser; `/mcp auth` signs in again. Google has since moved Gemini CLI users to Antigravity CLI.

## In code

An agent you build yourself connects with a token your server accepts. To act for a user, run the OAuth flow from [Set up agent access](/sign-in-setup/agent-access) to get one; never ship a user's token in source.

**OpenAI Agents SDK (Python):**

```python
import os

from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async with MCPServerStreamableHttp(
    name="acme",
    params={
        "url": "https://app.example.com/api/mcp",
        "headers": {"Authorization": f"Bearer {os.environ['ACME_TOKEN']}"},
    },
) as acme:
    agent = Agent(name="Assistant", mcp_servers=[acme])
    result = await Runner.run(agent, "List my workspaces.")
```

**LangChain** (`pip install langchain-mcp-adapters`):

```python
import os

from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient(
    {
        "acme": {
            "transport": "http",
            "url": "https://app.example.com/api/mcp",
            "headers": {"Authorization": f"Bearer {os.environ['ACME_TOKEN']}"},
        }
    }
)
tools = await client.get_tools()
```

LangChain 1.4 and later also ship MCP support in the `langchain.mcp` namespace (in beta), with a different configuration: see LangChain's [migration guide](https://docs.langchain.com/oss/python/migrate/langchain-mcp-adapters).

## List it on the MCP Registry

The [MCP Registry](https://registry.modelcontextprotocol.io) lists servers that clients and marketplaces read. A remote server's `server.json` names its endpoint under `remotes`:

```json
{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "com.example/acme",
  "title": "Acme",
  "description": "Notes, reports and jobs in Acme, for the signed-in user.",
  "version": "1.0.0",
  "remotes": [
    { "type": "streamable-http", "url": "https://app.example.com/api/mcp" }
  ]
}
```

A name under your own domain, such as `com.example/acme`, needs DNS or HTTP authentication. Install the official `mcp-publisher` CLI, then run `mcp-publisher login dns` (or `http`) and `mcp-publisher publish`. The registry is in preview.

> **Note:**
  SDK 1.0.0 adds commands for the rest of this page: `npx buildbase agent install --url <mcp-url>` prints every link and snippet above for your server, `npx buildbase agent listing --url <mcp-url>` writes the registry's `server.json` and the Claude and ChatGPT submission checklists from your running server, and `buildMcpInstallLinks()` renders the install buttons on your own docs page.


## If something goes wrong

| What you see                                      | Why                                                             | What to do                                                                                            |
| ------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| The client cannot register or sign in             | **Let agents register themselves** is off, or no base client    | Turn it on with a base client in [Set up agent access](/sign-in-setup/agent-access)                   |
| Claude or ChatGPT cannot reach the server         | The URL is not public HTTPS, or a firewall blocks their servers | Serve it on public HTTPS; allow the provider's addresses if you filter by IP                          |
| The agent sees fewer tools than you defined       | Tools that need a scope the token lacks are hidden              | Ask for the scope when the agent signs in, or remove `requiredScopes` from the tool                   |
| A tool call fails with a protocol error, not text | The result does not match the tool's `outputSchema`             | Call the tool and compare its `structuredContent` with its `outputSchema`; fix the tool or its schema |

## Next steps

- [MCP and agents](/reference/mcp-agents): build the server, your own tools and the built-in ones.
- [Set up agent access](/sign-in-setup/agent-access): the consent screen, scopes and self-registration.
- [Device code](/authentication/device-code): sign-in for a device or a terminal without a browser.