Which surface do I want?
Choose where to do the work and where to review it. Your agent can work through MCP while Studio keeps the saved investigation available to inspect and continue. The Hub provides published Labs, and the runtime runs Labs on your own machine.
| Surface | Use it for | How you sign in | It cannot |
|---|---|---|---|
| Studio (browser) | Starting sessions, inspecting saved work, reviewing evidence and continuing investigations | Sign in or create an account to use Studio | Read files on your machine or automatically import an external assistant’s conversation |
| MCP (Claude, ChatGPT/Codex) | Letting your agent use the same sessions, Labs, runs and evidence | Sign in through your assistant’s browser setup; no CLI needed | Execute changes, compute or publication without the required access and approval |
| Hub (browser) | Browsing published labs and seeing what they are made of | Nothing. Browsing is open, and account actions hand off to Studio | Run anything itself |
| Developer API | Working with sessions, Labs and managed runs from your own code | A developer API key in Authorization | Provide a conversational assistant |
Biosimulant runtime and its CLI (pip install biosimulant) | Building and running labs on your own machine, CI, containers | auth login --web in the browser, or a developer API key — and only for private pulls or publishing | Create account workspaces, managed Runs, or Passports |
The first four need no install. The runtime is the open-source package the other four are built on, and it is the only row you have to put on a machine yourself.
Connecting an agent
For Claude or ChatGPT/Codex, follow the app setup steps. They include the server URL, OAuth registration setting, and a first request to verify the connection.
If you want Claude or ChatGPT/Codex to use Biosimulant, you want
MCP. You do not need to pip install biosimulant
and you do not need a token. Sign-in happens in your client’s browser
consent flow.
biosimulant auth login is for the local CLI only. It asks for a registry
token because the CLI talks to the Hub’s package registry, which is a different
thing from the agent gateway. Installing the CLI will not connect an agent, and
signing an agent in will not authenticate the CLI.
An agent may still use the CLI once it is connected — a local coding agent with a shell will run labs locally when your machine can handle them, because that is faster and free. That is an optimisation, not a requirement. Nothing an agent needs from your account depends on the CLI being installed.
What each credential is
| Credential | Issued by | Used by | Revoke at |
|---|---|---|---|
Developer API key (bsk_live_…) | Developer console, or biosimulant auth login --web | CLI registry operations, Developer API | Developer console |
| MCP authorization | Browser consent in your agent client | The MCP server only | Settings → Connections |
Never paste an access token, refresh token, authorization code, or session cookie into a prompt or a project file. The sign-in flows handle credentials so you don’t have to.
Running: local or managed
Both are real, and they produce different things.
- Local —
biosimulant labs run, orBioWorld.run()in Python. Free, offline, no account. Use it for iteration. It produces results on your machine; it does not produce a managed Run or a Passport. - Managed — the Developer API, Studio, or an agent over MCP. Runs on Biosimulant compute with the runtime and inputs recorded, and yields a durable Run you can recover after disconnecting, plus a signed Evidence Passport.
Use local while you’re developing and managed when the result has to be reproducible by someone else. A local run is evidence; it is not a substitute for a managed run that was asked for.
Check whether this machine can run a lab locally at all:
biosimulant labs capabilities ./my-lab --json