Docs
Sign inJoin the waitlist

Use Facet from an agent

Facet runs a remote MCP server at https://facet.halfspacelabs.com/mcp. From your agent you can make a Model, ask for a change, start a fix once you approve its quote, and call the result. Facet does the work of building and improving the Model; your agent only says what it needs.

The web app shows the same Models, for watching, approving and settings. You can also make Models from Slack. In the tools, the live version of a Model is called Latest.

Connect

Facet is invite-only for now: join the waitlist first, then sign in with the email we invite. Most clients sign you in with a browser popup (OAuth) the first time; there is no key to paste. If the popup shows a waitlist form instead of sign-in, that email isn’t invited yet.

Claude Code

Install the plugin. It brings the server and four commands.

claude plugin marketplace add halfspacelabs/facet-plugins && claude plugin install facet@facet

Or add the server alone:

claude mcp add --transport http facet https://facet.halfspacelabs.com/mcp

To sign in, restart Claude Code, run /mcp, choose facet, then Authenticate.

Other clients

Client How to add Facet
Claude (claude.ai and the desktop app) Settings, Connectors, Add custom connector, with the URL above
Cursor Add to Cursor in the Agent view of any Model’s Overview, or add {"mcpServers": {"facet": {"url": "https://facet.halfspacelabs.com/mcp"}}} to ~/.cursor/mcp.json
VS Code Add to VS Code in the same Agent view, or run MCP: Add Server with the URL
ChatGPT Settings, Apps and Connectors, Create, with the URL above (developer mode)
Codex codex mcp add facet --url https://facet.halfspacelabs.com/mcp

With an API key

A client that can’t sign in can send an API key instead: Authorization: Bearer fct_.... A key acts with its own role and Model scope, and never approves a quote or a merge: with a key, a person approves in the web app. A key also can’t create a Model, upload data or import a Model; those need a signed-in person, so they answer not_allowed with a key.

Commands in Claude Code

The plugin’s Skills are commands in Claude Code; other agents use the same Skills when they fit.

  • /facet:find: find the LLM calls in your repo a Model could take over, ranked by what each would save. Sends nothing to Facet.
  • /facet:new <file:line>: make a Model from one call, with the real inputs and output shape your code already has.
  • /facet:wire <model>: once v1 merges, compare it on your repo’s examples, then swap the call over through the OpenAI SDK.
  • /facet:status: the Models your repo calls, how each scores on its evals, and any Change in flight.

What your agent sends

Nothing leaves your machine until you’ve seen it and said yes: the description, how many rows, which files they came from, and a few rows as they will be sent.

  • Rows come from your repo’s tests, fixtures, sample files and few-shot examples, never production logs or databases unless you point at a file.
  • The agent never opens .env or credential files, and drops rows that look like keys or tokens.
  • It flags personal details and offers to mask them before sending.
  • It sends an output only when a person wrote it, never an LLM’s answer: Facet doesn’t train on frontier model outputs.
  • The plugin runs no code on your machine: it is the server’s address and Markdown instructions.

How an agent uses it

  1. create_model with a plain description of the task and a few sample inputs. It returns a review of the draft, with nothing made yet: the input and output schemas, each eval, where the training rows come from, the rows it dropped and why, and v1’s quote. Review it and show the person. To change it, call create_model with the draft_id and the changes as description: Facet’s agent redrafts the same draft and returns a new review.
  2. create_model again with the draft_id and confirm: true after their yes, with drop_evals for any eval they reject. It returns the Model and a Planned Change that builds v1, with its quote. start_change with their yes builds v1, and once it merges the Model is callable with the OpenAI SDK.
  3. request_change when the Model should get better, in plain words, with examples of misses. This makes a Change at once: Facet drafts the eval, measures Latest and quotes it. Until it starts, the Change has an id and no number.
  4. Show the person the plan and quote. start_change only with their yes: your client asks them to confirm, because the tool spends money. A Change never spends more than its quote.
  5. get_change to follow it. A Change runs for minutes to hours, so in Claude Code the agent offers to watch it with /loop while the session stays open, and tells you when it is Ready or needs you. Once it merges, the new Version is Latest. try_version calls it once; rollback undoes a merge in one step.
  6. If v1’s Change fails, get_change lists ways to train it again, each with a base and a quote. Show the person; train_again with their yes.

Each result that asks you to decide something (a draft, a quote, what a Change did, an approval) carries review_url, its page in Facet. An agent with a browser beside you, such as an integrated browser, opens it there; others give you the link.

The use-facet Skill, in the Facet plugin, teaches agents this flow and when Facet fits.

Paste this into your agent

Once Facet is connected, these prompts run the whole loop:

Use Facet to make a Model that labels our support tickets billing, bug or account, and marks
urgent ones. Here are ten real tickets from last week: ... Show me the draft and the quote
before you approve anything.
Our support-triage Model labels refund requests as account. Ask Facet to fix it, with these
three tickets as examples, and show me the quote.
Check on the support-triage fix. When it merges, try it on "I was charged twice" and show me
the answer.

Toolsets and modes

Tools come in toolsets. models, changes and versions are on by default; workspace (keys, members, policy, spend limit) is opt in. Pick them with the X-MCP-Toolsets header (models,changes, all) or, for clients that only take a URL, the query string: https://facet.halfspacelabs.com/mcp?toolsets=all.

  • Read-only mode (X-MCP-Readonly: true or ?readonly=true) lists only the tools that read.
  • Lockdown mode (X-MCP-Lockdown: true or ?lockdown=true) hides text that people or data wrote (Change requests, examples, model answers, eval statements, Instructions) from every result, so nothing a tool returns can carry a prompt injection. Names, numbers, states, scores and quotes stay.
  • Workspace: you act in your shared workspace if you have one, else Personal; X-MCP-Workspace or ?workspace= picks another by ID. A draft’s review names the workspace the Model will be made in.

Every tool follows the same policy as the web app: your role, the Model’s rules, the quote cap and the spend limit. Tools that spend money or change who can act are marked destructive, so clients confirm them with you.

Tools

models (on by default)

Tool What it does
list_models List the workspace’s Models: each one’s name, Latest Version, accuracy and status (training, needs approval, failing). Read-only.
get_model A Model’s page: Latest Version, its scorecard (each eval, passing or failing), open Changes and what needs the person. Read-only.
create_model Make a new Model from a plain description of the task (and sample inputs, if you have them), in two steps. First Facet drafts the name, schemas, Instructions and evals and writes the training data, and returns a review with nothing made yet: the schemas, each eval, the data mix, the rows it dropped and why, and v1’s quote. Review it, show it to the person, then call create_model again with the draft_id and confirm true to create the Model with a Planned Change to train v1. To change the draft instead, call create_model with the draft_id and the changes as description: Facet’s agent redrafts the same draft and returns a new review. Once the person approves that quote, start_change starts it, and once v1 merges, the Model is callable through the OpenAI SDK, with the Model name as the model. Drafting takes a minute or two: if the result says drafting, call create_model again right away with the draft_id it gave. Each call waits up to 40 seconds for the draft itself, so never sleep or wait before calling again. With import, the Model starts from the person’s own LoRA adapter on Qwen3.5, in a public Hugging Face repo or uploaded with import_model (import with only its id), and v1 is that adapter, live and callable at Create and scored after (a red eval never takes it down); Create then needs attest true on the person’s yes to the review’s attestation. Send 10 to 20 of the person’s own calls with what their runtime answered as import.parity_pairs, so Facet checks it serves the model as they do; without them v1 is live but can’t train. An import’s later Changes train from that adapter and, once Ready, wait for a Model owner’s approval before they replace it (merge_change), unless merge_protection is open.
list_evals A Model’s evals: each by its short name and the plain statement every Version is scored on, with its pass rate. Read-only.
get_eval One eval: its short name, statement, grader, bar and example counts. Read-only.
add_eval Add an eval to a Model. Usually not needed: request_change drafts the eval a Change implies.
edit_eval Edit or rename an eval. Loosening one waits for a Model owner’s approval; a rename (name) never waits and re-runs nothing.
add_examples Add examples (input, and the reference output if there is one) to an eval. They train and score only this Model.
create_upload Start an upload of training data or eval data for create_model or request_change. Training data trains the Model; eval data is hidden whole and scores it, and no agent or teacher reads it. Send rows with add_upload_rows, then pass the upload’s id as training_upload or eval_upload.
add_upload_rows Add up to 1,000 rows (input, and output for eval data) to an upload; call again for more. Up to 20,000 training rows and 5,000 eval rows per upload. Always send after: the rows the upload held before this call (0 first, then rows from the last result). If a call times out, send it again unchanged: a call whose rows already landed is refused with the number of rows the upload holds, so nothing is added twice; carry on from that number.
get_upload An upload: its kind, rows and how many are hidden so far. Read-only.
add_correction Send the right answer to one call a Model got wrong: the call’s input and the answer it should have given, with its request_id if you have it. It joins the Model’s capture dataset within the hour, and the next Change trains on it as given. Works once data capture is on for the Model; until then it is refused. Use it only for answers the person or their own system knows are right, never for answers you wrote.
create_dataset Start a workspace dataset of real production rows, up to millions, that every Model can draw on. Name the input column, and if the files have them, the expected output column, metadata columns, a group_key column (rows that belong together, such as one customer’s) and columns to drop. Set expected_output_origin to who wrote the answers: only human or own_system answers train; frontier_model or unknown rows are used as inputs only. Then send each file with create_dataset_upload.
create_dataset_upload Send one CSV or JSONL file (gzip allowed) of up to 5 GB to a dataset. Give its exact size in bytes. The result has upload_url: PUT the file’s bytes there yourself (curl -T file ‘upload_url’), never through this conversation. A file over 1 GB has parts instead: PUT each 256 MB part to its URL and keep each response’s ETag. If neither is there yet, call get_dataset in a few seconds. Then call complete_dataset_upload.
complete_dataset_upload Say a dataset file is in place, with each part’s ETag for a file sent in parts. Facet reads it in a sandbox with no network, splits it (10% hidden, which no agent ever reads; groups stay on one side) and makes the dataset’s next version. It takes minutes for a large file: follow it with get_dataset. Once it has a version, pass its name as dataset to create_model or request_change.
import_model Upload the person’s own LoRA adapter on Qwen3.5 0.8B or 4B, as PEFT saves it: adapter_config.json and adapter_model.safetensors, plain LoRA, rank 64 at most, 1 GB at most. Give each file’s exact size in bytes. The result has config_url and weights_url: PUT each file’s bytes there yourself (curl -T adapter_config.json ‘config_url’), never through this conversation. Then call complete_import with adapter_model.safetensors’ sha256 (sha256sum).
complete_import Say an upload’s two files are in place, with adapter_model.safetensors’ sha256. Facet checks the files (its shapes pick the base; NaN, infinity, rsLoRA, other adapter types and full weights are refused) and runs it beside the base on Facet’s own GPU. Then call create_model with a description of what the adapter does and import {id: this import’s id}, plus its system_prompt or no_system_prompt; create_model waits on the checks.
get_dataset A dataset: its columns’ roles, its latest version’s rows in train and hidden, twins, and a profile of the train split in aggregates only (never rows), its versions, and your files on their way in with their state or why one failed. Read-only.
list_datasets The workspace’s datasets, newest first, each with its latest version’s rows. Read-only.
start_scan Scan a dataset of the person’s model calls to find where a Facet Model would save money. Code groups the calls by trace name, model and system prompt and counts calls, tokens and logged cost in Facet’s hidden environment; nothing is sent to any model and it spends nothing. When the workspace’s scans are judged, the Facet Agent then reads some of the training side’s calls to judge the groups, within the scan’s own budget; such a workspace starts 3 scans a month. Map the dataset’s model, trace_name, input_tokens, output_tokens, cost and called_at columns at create_dataset for the best numbers. If the calls name no model, pass the frontier model they use today as model. It takes a minute or more: follow it with get_scan. With no dataset_id it starts nothing and returns review_url, Facet’s Scan screen, where the person connects Langfuse or uploads a file themselves: keys and files are entered there, never through this tool.
get_scan A scan: measuring, failed, or ready with its groups of calls ranked by what Facet saves, each with its calls, the model today, its cost today and on Facet, and whether that cost was logged, a list price or an estimate. Figures are a month’s only when the calls’ times are mapped; otherwise they are the dataset’s. Aggregates only, never rows. When the workspace’s scans are judged, judge says where the Facet Agent’s judging stands, each group it judged has fit (fit, classifier or not_a_fit) and reason, a fit also its task, evals and draft_id, the draft Facet opened for it (create_model with that draft_id reviews it, and nothing spends until the person approves), and calls_read is how many calls it read itself. Read-only.
export_model Take a Version out of Facet as plain data, Latest unless version is set: its Instructions, each eval it was scored on with its grader and bar, their training examples, and download links for its training data (OpenAI chat JSONL) and evals (JSONL), which take the same key. Held-out examples stay hidden. Read-only.

changes (on by default)

Tool What it does
list_changes A Model’s Changes: each one’s state (planning, planned, queued, running, ready, merged, failed, closed), quote, and its number once it starts or its id before. Read-only.
get_change One Change, by its number or, before it starts, its id. Planned: its plan (the drafted eval, what Latest gets wrong, a quote per approach). Running: its steps, its spend against its quote, and its timeline, every phase so far in plain words with when it began and how long it took, such as Getting a GPU, Learning or Starting the model; tell the person the live one. Ready: what got better and worse. A running Change takes minutes to hours: to follow one, schedule this call every few minutes if your client can (Claude Code: /loop) rather than asking the person to check back. Read-only.
request_change Ask for a Model to get better at something, in plain words, with examples of where it falls short if you have them. This makes a Change at once, Planning: Facet’s own agent drafts the eval it implies, runs it on Latest to show what Latest gets wrong, and quotes it. Nothing is spent until start_change. Planning takes a minute: if the result is still planning, call get_change with its id later.
start_change Start a Planned Change, by its id, accepting its quote: it spends up to the quote and never more, and gets its number. Show the person the plan and quote first and start only with their yes. approach is instructions (no training, cheapest) or train. Asks the person to confirm.
file_ask Old name for request_change, returning an Ask.
get_ask Old: an Ask, by its number. Read-only.
approve_plan Old name for start_change, by the Ask’s number. Asks the person to confirm.
close_ask Old name for close_change on a Planned Change, by the Ask’s number.
answer_change Answer the question Facet’s agent asked on a Change (get_change shows it under question), in the person’s words: the agent goes on with it in the same conversation. Ask the person; never answer for them. With no answer by question.expires_at the agent goes on with question.default.
stop_change Stop a running Change now. It spends nothing more; Latest stays as it was.
close_change Close a Change without merging it: a Ready or stopped one, or a Planning or Planned one without starting it. On a Planned Change that Latest already gets right, add_eval keeps its drafted eval first.
raise_quote Continue a Change that stopped at its quote, with a higher quote. Spends money: only with the person’s yes. Asks the person to confirm.
train_again Train v1 again after its Change failed. get_change lists the options under failure.train_again: a base_model, its typical price and its quote. The new Change starts at once and spends up to that quote: show the person the options first and call only with their yes. Empty base_model keeps the Model’s base. Asks the person to confirm.
merge_change Merge a Ready Change: its Version becomes Latest, which callers get at once. Rollback undoes it in one step. Asks the person to confirm.
list_approvals Approvals waiting for the signed-in person, such as a merge when the Model has Approve each merge on, ready drafts and Planned Changes they may start, and updates: Changes they started that went live, asked a question or failed in the last 3 days. Facet pushes nothing to you, so tell the person about new updates. Read-only.
answer_approval Approve or reject a waiting approval. Only with the person’s yes. Asks the person to confirm.

versions (on by default)

Tool What it does
list_versions A Model’s Versions, newest first, with which one is Latest. Read-only.
get_version One Version, like a model card: what changed, accuracy, latency, cost per 1,000 calls and per 1,000 correct answers (per_1k_correct_micros), the evals it passes and fails, and its comparisons with frontier models (compare_version). Read-only.
try_version Call a Model’s Version once with an input and get its answer, as an app would. Latest unless version is given. Metered like any call. After sitting idle a Version takes about 3 minutes to start: an error saying it hasn’t answered yet means try again in a minute, and the call keeps it starting.
compare_version Score a Version and one or more frontier models (anthropic/claude-opus-5.5, anthropic/claude-sonnet-5.5, anthropic/claude-haiku-5.5, openai/gpt-5.5, google/gemini-3.8-flash, deepseek/deepseek-v4.1-flash) on the same hidden rows: correct answers and what 1,000 correct answers cost on each side. Without confirm it only quotes and says which providers would get the rows; show the person that, and call again with confirm true only after their yes. It spends at cost, from the free credit or the month’s spend. A provider an Owner hasn’t turned on in Settings is refused. It runs in the background: get_version shows each comparison under comparisons when it finishes. Asks the person to confirm.
rollback Point Latest at an earlier Version, or undo the last rollback. One step, always reversible.
go_live Take a pilot from a scan live (get_model shows trial): from now it answers every key of the workspace, as any Model, and its dataset is kept. Until then it answers Try it only. Needs a merged v1. Call with confirm true only after the person’s yes. Asks the person to confirm.

workspace (opt in)

Tool What it does
get_me The signed-in person, their workspaces and the base URL Models are called on. Read-only.
get_spend This month’s spend and the workspace’s monthly spend limit. Read-only.
set_spend_limit Set the workspace’s monthly spend limit, in micro-dollars. Workspace Owners only. Asks the person to confirm.
get_billing The workspace’s plan, the free credit left and recent invoices. Plans and cards change in the web app’s Settings. Read-only.
get_usage A month’s spend and serving calls by day, Model, key and Change; this month unless month (as 2026-10) is set. Read-only.
list_members The workspace’s members and pending invites. Read-only.
set_member_role Change a member’s workspace role. Asks the person to confirm.
remove_member Remove a member from the workspace. Asks the person to confirm.
invite Invite someone to the workspace by email.
withdraw_invite Withdraw a pending invite.
list_keys The workspace’s API keys (never their secrets). Read-only.
create_key Make an API key for calling Models, optionally limited to one Model. The secret is in this result only: hand it to the person or put it in their app’s secrets, never in code.
revoke_key Revoke an API key at once. Asks the person to confirm.
get_model_settings A Model’s policy: merge protection, who may start Changes, and its owners. Read-only.
set_model_settings Change a Model’s policy. Model owners only. Asks the person to confirm.
submit_feedback Send Halfspace, who make Facet, feedback about Facet or one of its tools. Call it only when the person asks you to send feedback, never on your own. Write what they said: what they tried, what they expected and what happened, and name the tool in tool when it is about one. Leave out keys, secrets and example data. A person reads every one; nothing replies here. Listed in every toolset, read-only mode too.

Slack

Facet also works in Slack. A workspace Owner adds it once from Settings in the web app, and chooses what Facet for Slack may do.

  • Ask: mention @Facet in a channel, or send it a message. Say what the task is and attach a few examples as a file if you have them.
  • Review: Facet replies in the thread with the draft, its evals and a quote.
  • Approve: press Approve in Slack. The first time, you link your Slack account by signing in, so the approval acts as you.
  • Fix: when an answer is wrong, tell @Facet in plain words. It turns that into an eval and quotes the fix.

The web app shows the same Models and Changes, so you can review there instead.

Next steps

Esc