# Connect Facet

Facet builds, evaluates and serves a small model for one task a product repeats. Its agent does the ML work; you reach it through an MCP server:

```text
https://facet.halfspacelabs.com/mcp
```

Sign-in is OAuth in the browser. There is no key to paste.

## First: can you run commands on this machine?

- **Yes** (Claude Code, Codex, Cursor, VS Code, OpenCode, Gemini CLI and similar): do the setup yourself with the steps below, check it, then tell the person what you changed.
- **No** (a chat app such as claude.ai or ChatGPT): you can't add it yourself. Give the person these steps:
  - **Claude:** Settings, Connectors, Add custom connector, paste the URL above, then Connect.
  - **ChatGPT:** Settings, Apps and Connectors, Create (developer mode), paste the URL above.

## Talk to the person briefly

Two or three sentences at a time. The person does one thing: sign in once in the browser. Do everything else.

## 1. Add the server

Use the section for the client you are running in. Add it for the user, not one project, so it works in every repo.

### Claude Code

Install the Facet plugin. It brings the server and the commands `/facet:find`, `/facet:new`, `/facet:wire` and `/facet:status`:

```sh
claude plugin marketplace add halfspacelabs/facet-plugins
claude plugin install facet@facet
```

If plugins aren't available, add the server alone:

```sh
claude mcp add --transport http --scope user facet https://facet.halfspacelabs.com/mcp
```

Then ask the person to run `/reload-plugins` (or restart Claude Code), run `/mcp`, choose **facet** and **Authenticate**.

If the `claude` command isn't found (for example in the Claude desktop app), ask the person to add Facet in Claude's Settings, Connectors, Add custom connector, with the URL above. Claude Code uses the connectors of the account it signs in with.

### Codex

```sh
codex mcp add facet --url https://facet.halfspacelabs.com/mcp
codex mcp login facet
```

`login` opens the browser. Without a local browser, add `--no-browser` and give the person the printed link. The Codex app, CLI and IDE extension share this config; the app needs a restart to load it.

### Cursor

Add Facet to `~/.cursor/mcp.json`, keeping any servers already there:

```json
{ "mcpServers": { "facet": { "url": "https://facet.halfspacelabs.com/mcp" } } }
```

Or give the person the one-click link: cursor://anysphere.cursor-deeplink/mcp/install?name=facet&config=eyJ1cmwiOiJodHRwczovL2ZhY2V0LmhhbGZzcGFjZWxhYnMuY29tL21jcCJ9. Then ask them to open Cursor Settings, MCP, and sign in next to facet.

### VS Code (Copilot)

```sh
code --add-mcp '{"name":"facet","type":"http","url":"https://facet.halfspacelabs.com/mcp"}'
```

Or give the person the one-click link: vscode:mcp/install?%7B%22name%22%3A%22facet%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Ffacet.halfspacelabs.com%2Fmcp%22%7D. VS Code asks them to sign in the first time a Facet tool starts.

### OpenCode

Add Facet under `mcp` in `~/.config/opencode/opencode.json`, keeping what is there:

```json
{ "$schema": "https://opencode.ai/config.json", "mcp": { "facet": { "type": "remote", "url": "https://facet.halfspacelabs.com/mcp" } } }
```

```sh
opencode mcp auth facet
```

### Gemini CLI

```sh
gemini mcp add --transport http --scope user facet https://facet.halfspacelabs.com/mcp
```

Then ask the person to run `/mcp auth facet` in Gemini CLI.

### Any other client

Facet is a remote MCP server over streamable HTTP with OAuth (dynamic client registration and client ID metadata documents). Add the URL above the way your client adds remote servers.

## 2. Sign in

Sign-in opens https://facet.halfspacelabs.com/auth/login in the browser. Facet is invite-only for now: if the page shows a waitlist form instead of sign-in, the person's email isn't invited yet. Point them to https://halfspacelabs.com/waitlist and stop there. Never ask for their email yourself.

A client that can't do OAuth can send an API key the person makes in the Facet web app, as `Authorization: Bearer fct_...`. Don't make the key for them. A key never approves a quote or a merge, and can't create a Model, upload data or import one: those need the person signed in, so with only a key, point them to the web app for those steps.

## 3. Check it

Most clients load a new server only in a new session. Before the restart, tell the person in one line what to do after it, for example: "Restart, sign in to facet when asked, then say: find a call Facet can take over."

Once the tools are loaded, call `list_models`. An empty list is a working connection.

## 4. Start

Ask the person where to start:

- **From this codebase:** find one narrow LLM call (classify, extract, route, score, rewrite) and make a Model from its real inputs. In Claude Code, that is `/facet:find`.
- **From a description or a dataset:** call `create_model` with a plain description of the task and a few real examples.

`create_model` returns a draft to review and makes nothing. Show it to the person. Nothing spends until they approve the quote, which is a hard cap.

## Ground rules

- Send nothing to Facet until the person has seen what will go: the description, how many rows, and a few rows as sent.
- Never open `.env` or credential files. Drop rows that look like keys or tokens.
- Never send an LLM's answers as examples of right outputs. Facet doesn't train on frontier model outputs.
- Never write prompts or training data for Facet. Its agent does that.

## More

- Docs for agents: https://halfspacelabs.com/docs/agents.md
- The prompt that starts this page: `Read https://halfspacelabs.com/setup.md and connect Facet for me.`
