Endpoints
The server keeps no session, so a host can retry any call on any connection.
Install
Install the Obss Plugin. It adds the Obss MCP server, not the docs server. To add the docs server, or when your host has no plugins, see Connect without the plugin.Sign in
The first time your host connects, it opens Obss sign-in in your browser. Sign in, and choose an organization if you belong to more than one. The server uses OAuth only: personal API keys are for the CLI. Every tool acts as you, in the organization you signed in to, with the same access you have in the dashboard. If your sign-in names no organization and you belong to several, calls fail withorganization_ambiguous: sign in again and choose one.
Organization check
Every tool that changes data takes an optionalexpected_organization_id. Send the organization.id from get_identity or get_project_context on every write. If your sign-in has moved to another organization, the call changes nothing and returns organization_scope_changed.
Projects
The server has no current project. Project-scoped tools take an optionalproject_id (prj_); without it, the server picks a project for that call only. To stay in one project, pass its project_id on every call. Tools that name a record by a unique ID, such as a pub_ public link, need no project.
A project_id you can’t read returns project_not_found, and no project at all returns project_required. Create one with manage_project.
Approvals
The server tells your host what each tool does, and your host decides how to ask you. Obss never asks for a confirmation code, a typed phrase, or a second call.
The irreversible tools are
delete_project, delete_resources, delete_schedule, and delete_tag. Claude Code in non-interactive mode (claude -p) refuses them.
You approve each call of launch_experiment, rerun_experiment, test_custom_agent, manage_schedule, trigger_evals, trigger_insights, publish_experiment, and update_experiment_publication. Only update_experiment_publication is marked destructive, so in hosts other than Ask Obss, turn on tool approval for the others to confirm each call.
Preview before you change
When a change’s effect isn’t obvious, run its read-only preview, show the result to the person, then make the change.Secrets stay in the dashboard
OAuth grants, API keys, secret headers, secret values, and payments stay in the dashboard; no tool accepts them. A definition names each value it needs as${NAME}, never the value, and install commands can’t use Variables (Keys in a URL or an argument).
When a step needs a secure value, the tool returns the exact dashboard link, often as setupUrl. Open it where you’re signed in, enter the value, and continue in your AI assistant. An argument that looks like a secret returns secure_input_requires_web, and the value is never repeated.
get_setup_linkslists each machine, MCP server, CLI, and SDK in the project that still needs a value or your account connection, with its link.inspect_mcp_accountchecks your connection to an MCP server in a treatment, with the link to fix it.refresh_mcp_server_toolsandlaunch_experimentnever send saved header values to an address no person bound them to. They returnmcp_tool_check_needs_webor themcp_header_values_unboundblocker, with the link where a person selects Refresh.inspect_quotaandlist_quota_ledgerreturn no billing link. Buy runs on Organization settings → Usage & billing (Runs and billing).
IDs
Tools take and return stable public IDs whose prefix names the record’s kind, such asprj_, exp_, or run_. Pass IDs exactly as a tool returned them, and don’t build them yourself. An agent key, such as claude-code, names an agent with any model, and a custom agent’s key starts with acp-. IDs and limits lists every prefix.
Paging
Reads return bounded pages. Alimit above the maximum is capped, not refused. Responses are capped at 20 KiB, so a page can hold fewer items than the limit.
Cursors expire after 30 minutes. An expired, changed, or foreign cursor returns
invalid_cursor, and one whose list changed returns stale_cursor; either way, start again without a cursor. A row too large for a response returns response_too_large.
Polling
Launches, Evals, Insights, uploads, and deletions finish after the call that starts them. Poll the matching read until it reports a final state:- Launches and experiments:
launch_experiment,rerun_experiment, andtest_custom_agentreturn alaunchId(adm_…) forget_launch_status. Onceexperiment.experimentIdis set, use it withget_experiment_statusand the other experiment tools. - Wait in the call: while
terminalis false, sendwait_ms(up to 25,000) to wait for a status change, a finished run, orterminal, or call again afterpollAfterMs. Whenterminalis true, read the final runs withlist_runs. If you calllist_runswhile await_msstatus call is still waiting,list_runscan answer first with an older state. - Evals and Insights:
get_evals_resultsandget_insights_resultsalso takewait_ms. A row isqueuedorrunninguntil its result is written;completed,skipped, andfailedare final. - The Brief: while
stateiswriting, callget_experiment_briefagain afterwaitMsmilliseconds. The differences and counts are already in that read. - Uploads: poll
get_uploaduntilstatusiscompleted,failed,cancelled, orexpired. - Deletions: poll
get_resource_deletionuntil the status is final. - Model lists: after
refresh_models, pollinspect_project_aiuntilcounts.modelRefresh.refreshingis 0. A provider’s models are readable earlier, once itsmodelRefresh.listedAtis set.
Progress counts
get_launch_status, get_experiment_status, and get_experiment return the same progress counts as obss experiments status, with each run in one state:
- A queued, running, or cancelled run counts in
queued,running, orcancelled(a blocked, then cancelled run iscancelled). - A completed or errored run counts in
passed,failed,infraBlocked,inconclusive, orerrored.
passed, failed, infraBlocked, inconclusive, cancelled, and errored add up to finished. infraBlocked (and infraBlockedCount in list_experiments) counts completed or errored runs that were blocked, so Evals didn’t check them.
Retries and concurrent changes
Hosts can lose responses, so each tool that starts work takes an attempt ID you choose. Use a new ID for each change and the same ID to retry: the retry returns the first result instead of doing the work twice. Reusing an ID for a different request fails with a conflict, such aslaunch_attempt_conflict or resource_mutation_attempt_conflict.
So that two people or AI assistants can’t overwrite each other, a change also sends the version you read. If the record changed since, nothing changes and the call returns an error: read again and retry.
Errors
A failed call returns an MCP tool error (isError: true). Its text is one JSON object:
code is stable, so your AI assistant or script can branch on it. message says what to do next. details appears only when it adds facts, such as a setupUrl or the current revision. Arguments that don’t match a tool’s schema fail before the tool runs, with a message that lists the fields the tool accepts.
Tool-specific codes, such as
schedule_limit_reached, are listed with each tool on Plugin (MCP) tools.
