Connect an AI agent to your app

Once your app serves MCP with @buildbase/sdk (MCP and 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; 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.

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

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 gives your app both.

Cursor

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

{
  "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:

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):

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

From a terminal:

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:):

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:

{
  "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

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):

{
  "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 to get one; never ship a user's token in source.

OpenAI Agents SDK (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):

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.

List it on the MCP Registry

The MCP Registry lists servers that clients and marketplaces read. A remote server's server.json names its endpoint under remotes:

{
  "$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.

If something goes wrong

Next steps

• MCP and agents: build the server, your own tools and the built-in ones.
• Set up agent access: the consent screen, scopes and self-registration.
• Device code: sign-in for a device or a terminal without a browser.