Skip to main content
The Obss MCP server lets your AI assistant create tasks and treatments, launch experiments, and read results. The Obss Plugin connects your host to it. These rules apply to every tool; Plugin (MCP) tools lists each one. Each tool matches a CLI command, with the same inputs, fields, and rules. Ask Obss uses the same tools in the dashboard and in Slack. This server is not one of the MCP servers you add to a treatment as tools.

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 with organization_ambiguous: sign in again and choose one.

Organization check

Every tool that changes data takes an optional expected_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 optional project_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_links lists each machine, MCP server, CLI, and SDK in the project that still needs a value or your account connection, with its link.
  • inspect_mcp_account checks your connection to an MCP server in a treatment, with the link to fix it.
  • refresh_mcp_server_tools and launch_experiment never send saved header values to an address no person bound them to. They return mcp_tool_check_needs_web or the mcp_header_values_unbound blocker, with the link where a person selects Refresh.
  • inspect_quota and list_quota_ledger return 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 as prj_, 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. A limit 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, and test_custom_agent return a launchId (adm_…) for get_launch_status. Once experiment.experimentId is set, use it with get_experiment_status and the other experiment tools.
  • Wait in the call: while terminal is false, send wait_ms (up to 25,000) to wait for a status change, a finished run, or terminal, or call again after pollAfterMs. When terminal is true, read the final runs with list_runs. If you call list_runs while a wait_ms status call is still waiting, list_runs can answer first with an older state.
  • Evals and Insights: get_evals_results and get_insights_results also take wait_ms. A row is queued or running until its result is written; completed, skipped, and failed are final.
  • The Brief: while state is writing, call get_experiment_brief again after waitMs milliseconds. The differences and counts are already in that read.
  • Uploads: poll get_upload until status is completed, failed, cancelled, or expired.
  • Deletions: poll get_resource_deletion until the status is final.
  • Model lists: after refresh_models, poll inspect_project_ai until counts.modelRefresh.refreshing is 0. A provider’s models are readable earlier, once its modelRefresh.listedAt is 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, or cancelled (a blocked, then cancelled run is cancelled).
  • A completed or errored run counts in passed, failed, infraBlocked, inconclusive, or errored.
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 as launch_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.

Tools by area

The server has 80 tools, grouped the same way as the CLI reference.

Next steps