# Plugin (MCP) reference - Obss

Plugin (MCP)
Plugin (MCP) reference
How the Obss MCP server works: endpoints, OAuth sign-in, approvals, web links for secrets, IDs, paging, polling, retries, and errors.
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
Server
URL
What it gives you
Obss MCP server
https://mcp.obss.app/mcp
Tools that read and change your projects, with OAuth sign-in
Obss product docs
https://docs.obss.app/mcp
Search over these docs
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.
Kind
What the server sends
What happens
Read-only
readOnlyHint: true
Changes nothing. Hosts usually run it without asking.
Changes data
readOnlyHint: false
Creates or changes records. Your host’s approval settings decide whether it asks.
Destructive
destructiveHint: true
Your host asks you first. The call acts as soon as it arrives.
Destructive · Irreversible
destructiveHint: true
and
_meta["anthropic/requiresUserInteraction"]: true
Can’t be undone. Hosts that read this key use their strongest confirmation.
You approve each call
No extra hint
Spends runs, creates a standing rule, or makes results public. Ask Obss asks before each 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.
Preview
Then
preview_delete_project
: a count of each kind of item, the running experiments it stops, and the blockers
delete_project
preview_delete_resources
: the plan, its
planHash
, and the blockers
delete_resources
with
plan_hash
preview_schedule
: the next 3 launches and the runs they use
manage_schedule
preflight_experiment
: blockers, setup links, and notices for a launch plan
launch_experiment
preview_evals
and
preview_insights
: which runs qualify and whether the models are ready
trigger_evals
and
trigger_insights
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.
Read
How to continue
Lists, such as
list_experiments
and
list_runs
While
hasMore
is true, send
nextCursor
as
cursor
, with the same filters.
Byte content, such as
get_run_transcript
and
get_run_output
Send the returned next offset as
offset
until
eof
is true. A page holds at most 12,288 bytes.
A run’s steps in
get_run_trajectory
While
truncated
is true, send
nextAfterOrdinal
as
after_ordinal
.
Version history in
inspect_resource
While
hasMore
is true, send
nextBeforeVersion
as
beforeVersion
.
Ranked analysis in
analyze_results
Never paged. When
page.truncated
is true,
page.completeData
names the full read:
query_data
or
get_run_trajectory
.
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
.
Tool
Attempt ID
launch_experiment
plan.launchAttemptId
rerun_experiment
,
test_custom_agent
,
get_experiment_plan
launch_attempt_id
manage_project
(create)
mutation_attempt_id
author_resource
,
bulk_author_resources
,
manage_resource
mutationAttemptId
on each operation
manage_schedule
(create and update),
delete_resources
,
publish_experiment
,
update_experiment_publication
attempt_id
trigger_evals
,
trigger_insights
trigger_attempt_id
complete_upload
upload_id
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.
Field you send
Read it from
Stale result
lock_version
(schedules, public links)
get_schedule
,
get_experiment_publication
schedule_changed
,
publication_changed
expected_updated_at
(tags, projects)
list_tags
,
get_project_context
tag_changed
,
project_update_stale
expectedUpdatedAt
(catalog records)
inspect_catalog
with
projection: "full"
resource_revision_conflict
expectedRevision
and the other revisions (agents, models, Obss AI features)
inspect_project_ai
configuration_changed
,
project_ai_configuration_changed
projectConfigurationRevision
,
organizationConfigurationRevision
(launch plans)
inspect_catalog
agent items, or
preflight_experiment
configuration_changed
plan_hash
(resource deletion)
preview_delete_resources
resource_deletion_plan_changed
Errors
A failed call returns an MCP tool error (
isError: true
). Its text is one JSON object:
{
"error"
: {
"code"
:
"schedule_changed"
,
"message"
:
"This schedule changed after you read it (lock version is now 4). Read it again, then retry."
,
"details"
: {
"lockVersion"
:
4
}
}
}
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.
Code
Meaning
organization_ambiguous
Your sign-in names no organization and you belong to several. Sign in again and choose one.
organization_required
Your sign-in has no organization.
organization_scope_changed
expected_organization_id
does not match your sign-in. Nothing changed.
forbidden
Your organization does not have access.
project_not_found
,
project_required
The project does not exist for you, or no project could be found.
secure_input_requires_web
An argument looked like a secret. Enter it on the web link instead.
mcp_tool_check_needs_web
The MCP server version’s saved values are not bound to its address. A person opens
setupUrl
and selects
Refresh
.
mcp_header_values_unbound
A launch or preflight blocker: an MCP server version would send saved values to an unbound address. Give the person
setupUrl
(the version’s
Tools
tab) to check the address and select
Refresh
, and don’t launch until they do.
invalid_cursor
,
stale_cursor
Read the first page again without a cursor.
response_too_large
One row or the fixed fields cannot fit a response. Narrow the read.
rate_limited
Too many calls. Wait and retry.
upstream_error
A service that Obss depends on did not answer. Retry.
internal_error
The request could not be completed.
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
.
Area
Tools
Identity and projects
get_identity
,
get_project_context
,
manage_project
,
preview_delete_project
,
delete_project
Catalog, resources, and uploads
inspect_catalog
,
browse_github_source
,
inspect_resource
,
inspect_resource_impact
,
author_resource
,
bulk_author_resources
,
manage_resource
,
download_resource_archive
,
create_upload
,
get_upload
,
complete_upload
,
cancel_upload
,
preview_delete_resources
,
delete_resources
,
get_resource_deletion
Experiments
preflight_experiment
,
launch_experiment
,
get_launch_status
,
list_experiments
,
get_experiment
,
get_experiment_status
,
get_experiment_plan
,
rerun_experiment
,
cancel_experiment
,
publish_experiment
,
list_experiment_publications
,
get_experiment_publication
,
update_experiment_publication
,
unpublish_experiment
,
get_public_experiment
Schedules
list_schedules
,
get_schedule
,
preview_schedule
,
manage_schedule
,
delete_schedule
Runs and results
list_runs
,
get_run_profile
,
get_run_trajectory
,
get_run_transcript
,
get_run_output
,
analyze_results
Frictions
list_frictions
,
get_friction
Evals and Insights
preview_evals
,
trigger_evals
,
list_evals
,
get_evals_results
,
get_evals_comparisons
,
get_experiment_brief
,
preview_insights
,
trigger_insights
,
list_insights
,
get_insights_results
Tags
list_tags
,
update_tags
,
rename_tag
,
delete_tag
Data
inspect_data_model
,
query_data
Agents, models, and setup
inspect_project_ai
,
manage_project_ai
,
delete_project_ai
,
test_custom_agent
,
get_setup_links
,
inspect_mcp_account
,
detect_mcp_auth_mode
,
list_mcp_server_tools
,
refresh_mcp_server_tools
Quota and notifications
inspect_quota
,
list_quota_ledger
,
list_notifications
,
acknowledge_notifications
,
inspect_notification_preferences
,
manage_notification_preferences
Ask Obss
disconnect_ask_oqo
Next steps
Plugin (MCP) tools
Every tool with its parameters and CLI command.
Install the Obss Plugin
Install the plugin in your host and sign in.
CLI reference
The same operations from your terminal and scripts.
IDs and limits
Every ID prefix and product limit.
Ask Obss
Tools
Powered by
This documentation is built and hosted on Mintlify, a developer documentation platform