> For the complete documentation index, see [llms.txt](https://beamline.gitbook.io/beamline-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://beamline.gitbook.io/beamline-docs/getting-started/connect-your-agent-to-beamline.md).

# Connect your agent to Beamline

Connect Claude Code, Codex, Cursor, Claude, VS Code, Gemini CLI, Windsurf, ChatGPT or any MCP client to Beamline's MCP server.

> The original of this page is on beamline.io: [beamline.io/connect](https://beamline.io/connect).

Beamline code and your custom style files live in your repo. Your app never depends on Beamline servers at runtime. The MCP server helps your agent find and install parts; you can also use the [local kit tools](https://beamline.io/docs/install).

Beamline's MCP server: <https://mcp.beamline.io/mcp> (remote, streamable HTTP). When your agent asks you to sign in, use Google, GitHub or an e-mail code: the free sample opens at once, and everything you bought comes with you. The agent then reads the menu (`beamline_capabilities`), installs the parts a screen needs (`beamline_install`) and checks the screen with the audit.

## Claude Code

1. **Add the server.** In any terminal.

   ```bash
   claude mcp add --transport http --scope user beamline https://mcp.beamline.io/mcp
   ```
2. **Sign in.** Type /mcp in Claude Code, choose beamline, then Google, GitHub or an e-mail code.
3. **Connect each app.** Once per app folder. Every later session there uses Beamline without being asked.

   ```bash
   npx --yes -p https://mcp.beamline.io/cli.tgz beamline-connect --hosted https://mcp.beamline.io/mcp
   ```

Or send Claude Code this message:

```
Set up Beamline for this app, so you build its UI from Beamline's React components.
1. Add the MCP server: run `claude mcp add --transport http --scope user beamline https://mcp.beamline.io/mcp`.
2. Connect this app: in its folder, run `npx --yes -p https://mcp.beamline.io/cli.tgz beamline-connect --hosted https://mcp.beamline.io/mcp`.
3. Ask me to type /mcp, choose beamline and sign in (Google, GitHub or an e-mail code).
4. When I say I'm signed in, call beamline_capabilities, read every part, and tell me Beamline is ready.
```

## Codex

1. **Add the server.** In any terminal.

   ```bash
   codex mcp add beamline --url https://mcp.beamline.io/mcp
   ```
2. **Sign in.** Opens your browser: Google, GitHub or an e-mail code.

   ```bash
   codex mcp login beamline
   ```
3. **Connect each app.** Once per app folder. Every later session there uses Beamline without being asked.

   ```bash
   npx --yes -p https://mcp.beamline.io/cli.tgz beamline-connect --hosted https://mcp.beamline.io/mcp
   ```

Or send Codex this message:

```
Set up Beamline for this app, so you build its UI from Beamline's React components.
1. Add the MCP server: run `codex mcp add beamline --url https://mcp.beamline.io/mcp`.
2. Sign in: run `codex mcp login beamline` and ask me to finish in the browser it opens (Google, GitHub or an e-mail code).
3. Connect this app: in its folder, run `npx --yes -p https://mcp.beamline.io/cli.tgz beamline-connect --hosted https://mcp.beamline.io/mcp`.
4. Tell me to start a new Codex session in this app: it loads the tools. From then on, call beamline_capabilities before any UI work.
```

## Cursor

One click: [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=beamline\&config=eyJ1cmwiOiJodHRwczovL21jcC5iZWFtbGluZS5pby9tY3AifQ%3D%3D)

1. **Add the server.** Cursor asks to install it.
2. **Sign in.** In Cursor Settings → MCP, click Needs login beside beamline: Google, GitHub or an e-mail code.
3. **Connect each app.** Once per app folder. Every later session there uses Beamline without being asked.

   ```bash
   npx --yes -p https://mcp.beamline.io/cli.tgz beamline-connect --hosted https://mcp.beamline.io/mcp
   ```

Or send Cursor's agent this message:

```
Set up Beamline for this app, so you build its UI from Beamline's React components.
1. Connect this app: in its folder, run `npx --yes -p https://mcp.beamline.io/cli.tgz beamline-connect --hosted https://mcp.beamline.io/mcp`. It adds the beamline MCP server and a Cursor rule.
2. Ask me to open Cursor Settings → MCP, turn beamline on and click Needs login (Google, GitHub or an e-mail code).
3. When I say I'm signed in, call beamline_capabilities, read every part, and tell me Beamline is ready.
```

## Claude

Claude on the web and the desktop app plans screens and reads every element. To install into your repo, use Claude Code.

One click: [Add to Claude](https://claude.ai/customize/connectors?modal=add-custom-connector\&connectorName=Beamline\&connectorUrl=https%3A%2F%2Fmcp.beamline.io%2Fmcp)

1. **Add the connector.** Opens Add custom connector with Beamline filled in. Click Add.
2. **Sign in.** Click Connect, then Google, GitHub or an e-mail code.
3. **Start a chat.** Ask for a screen and the elements it needs.

## VS Code

One click: [Add to VS Code](vscode:mcp/install?%7B%22name%22%3A%22beamline%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.beamline.io%2Fmcp%22%7D)

1. **Add the server.** VS Code asks to install it for GitHub Copilot.
2. **Sign in.** Start beamline when VS Code asks: Google, GitHub or an e-mail code.
3. **Connect each app.** Once per app folder. Every later session there uses Beamline without being asked.

   ```bash
   npx --yes -p https://mcp.beamline.io/cli.tgz beamline-connect --hosted https://mcp.beamline.io/mcp
   ```

Or send Copilot this message:

```
Set up Beamline for this app, so you build its UI from Beamline's React components.
1. Connect this app: in its folder, run `npx --yes -p https://mcp.beamline.io/cli.tgz beamline-connect --hosted https://mcp.beamline.io/mcp`. It writes the Beamline note into AGENTS.md.
2. Ask me to start the beamline server in VS Code when it asks, and sign in (Google, GitHub or an e-mail code).
3. When I say I'm signed in, call beamline_capabilities, read every part, and tell me Beamline is ready.
```

## Gemini CLI

1. **Add the server.** In any terminal.

   ```bash
   gemini mcp add --scope user --transport http beamline https://mcp.beamline.io/mcp
   ```
2. **Sign in.** Type /mcp auth beamline in Gemini CLI: Google, GitHub or an e-mail code.
3. **Connect each app.** Once per app folder. Every later session there uses Beamline without being asked.

   ```bash
   npx --yes -p https://mcp.beamline.io/cli.tgz beamline-connect --hosted https://mcp.beamline.io/mcp
   ```

Or send Gemini CLI this message:

```
Set up Beamline for this app, so you build its UI from Beamline's React components.
1. Add the MCP server: run `gemini mcp add --scope user --transport http beamline https://mcp.beamline.io/mcp`.
2. Connect this app: in its folder, run `npx --yes -p https://mcp.beamline.io/cli.tgz beamline-connect --hosted https://mcp.beamline.io/mcp`.
3. Ask me to type /mcp auth beamline and sign in (Google, GitHub or an e-mail code).
4. When I say I'm signed in, call beamline_capabilities, read every part, and tell me Beamline is ready.
```

## Windsurf

1. **Add the server.** Cascade → MCP → Open MCP config file, then add:

   ```json
   {
     "mcpServers": {
       "beamline": {
         "serverUrl": "https://mcp.beamline.io/mcp"
       }
     }
   }
   ```
2. **Sign in.** When Windsurf asks: Google, GitHub or an e-mail code.
3. **Connect each app.** Once per app folder. Every later session there uses Beamline without being asked.

   ```bash
   npx --yes -p https://mcp.beamline.io/cli.tgz beamline-connect --hosted https://mcp.beamline.io/mcp
   ```

## ChatGPT

ChatGPT plans screens and reads every element. To build in your repo, use Codex.

1. **Turn on developer mode.** Settings → Apps → Advanced settings. Paid plans only.
2. **Create the app.** Name it Beamline, paste this address and keep OAuth.

   ```
   https://mcp.beamline.io/mcp
   ```
3. **Sign in.** ChatGPT opens the sign-in: Google, GitHub or an e-mail code.

## Any MCP client

1. **Add the server.** Streamable HTTP; it signs in with OAuth.

   ```json
   {
     "mcpServers": {
       "beamline": {
         "url": "https://mcp.beamline.io/mcp"
       }
     }
   }
   ```
2. **Sign in.** When your client asks: Google, GitHub or an e-mail code.
3. **Connect each app.** Once per app folder. Every later session there uses Beamline without being asked.

   ```bash
   npx --yes -p https://mcp.beamline.io/cli.tgz beamline-connect --hosted https://mcp.beamline.io/mcp
   ```

Or send your agent this message:

```
Set up Beamline for this app, so you build its UI from Beamline's React components.
1. Add the MCP server "beamline" at https://mcp.beamline.io/mcp (Streamable HTTP; it signs in with OAuth).
2. Connect this app: in its folder, run `npx --yes -p https://mcp.beamline.io/cli.tgz beamline-connect --hosted https://mcp.beamline.io/mcp`.
3. Ask me to sign in when the server asks (Google, GitHub or an e-mail code).
4. When I say I'm signed in, call beamline_capabilities, read every part, and tell me Beamline is ready.
```

Each agent's page: [Claude Code](https://beamline.io/connect/claude-code.md) · [Codex](https://beamline.io/connect/codex.md) · [Cursor](https://beamline.io/connect/cursor.md) · [Claude](https://beamline.io/connect/claude.md) · [VS Code](https://beamline.io/connect/vscode.md) · [Gemini CLI](https://beamline.io/connect/gemini.md) · [Windsurf](https://beamline.io/connect/windsurf.md) · [ChatGPT](https://beamline.io/connect/chatgpt.md) · [Any MCP client](https://beamline.io/connect/any.md)

* [What Beamline is](https://beamline.io/) · [The component library](https://beamline.io/components/) · [Docs](https://beamline.io/docs) · [Get Beamline](https://beamline.io/checkout?pack=complete)
* Contact: <hello@beamline.io>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://beamline.gitbook.io/beamline-docs/getting-started/connect-your-agent-to-beamline.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.