Studio drafts and review
Save your edits to one MCP server's tools as a draft, then open one steering PR that a reviewer can judge.
You import an MCP server's tools in Studio, sort them, and shape them. Oxagen keeps those edits as a draft, so a closed tab loses nothing. When the edits are ready, select Open steering PR on the server's Changes tab. That step, called Review on this page, writes the server's folder to your workspace's steering repo as one steering PR. Nothing reaches production until that PR merges.
Three capabilities hold the draft and open the PR. You can call each one over the API or as an MCP tool.
| Capability | API route | What it does |
|---|---|---|
save_studio_draft | POST /v1/{org}/{ws}/tools/studio/draft | Saves the staged edits for one server folder |
get_studio_draft | POST /v1/{org}/{ws}/tools/studio/draft/get | Reads the stored draft |
open_studio_review | POST /v1/{org}/{ws}/tools/studio/review | Opens the steering PR, or adds a commit to the open one |
An org Owner or a workspace Admin can call all three. An API key you create acts with its own role, never its creator's, and never as an Owner or Admin. So it cannot call these three, on the API or through the MCP tool. Use the app instead.
Save a draft
Each server folder has one draft. The folder name is the server's name under tools/servers/.
- Stage your edits as
ops. An edit imports a tool, removes one, classifies one, rewrites its description, sets its result cap and paging, or saves a test call. One edit,expose, sets the server's exposure mode inserver.toml. - Send
server.tomland the source the tools import from, such as an OpenAPI document, a GraphQL schema,.protofiles, or an MCP server'stools/listresult. Omit either one to keep the stored copy. - Call
save_studio_draftwith the revision you started from.
The revision stops two tabs from overwriting each other:
revision: 0starts a new draft. It never overwrites a stored one.revision: Nsaves only when the stored draft is atN. Otherwise the save answersconflictwithdraft_revision_stale. Read the draft again withget_studio_draft, then save.- No revision saves over whatever is stored.
Each save raises the revision by one. The save runs every check before it writes, so a refused save stores nothing.
A draft holds at most 2,000 edits in 8 MiB, a 256 KiB server.toml, and a 25 MiB source. The API answers a request body over 36 MiB with 413 before it reads it.
Keep credentials out
A saved test becomes a line of tests/calls.jsonl in the steering repo, and a credential in git history costs a rotation. So Oxagen refuses a credential it can recognize by name.
server.tomlnames a credential by reference only, asoxagen:credential/<name>.- A saved test keeps the request as Studio built it, before the gateway added the credential.
- The save refuses a test whose request carries an
authorization,proxy-authorization, orcookieheader, withtest_holds_credential. Remove the header and save the test again. - It refuses the same way when any other header or query parameter has a name that reads like a credential, such as
X-Api-Keyor?access_token=. A server may place its key anywhere, and the draft does not say where. - Review checks the saved tests again before it writes anything. A draft stored before the save checked tests still opens no PR while a test in it carries one.
What this does not catch is a credential under a name that reads like nothing, such as ?v=. Read a saved test before you open the review.
Open the review
Select Open steering PR on the server's Changes tab, or call open_studio_review with the server name and the revision you reviewed. Review takes these steps:
- It reads the draft and refuses when the stored revision differs from yours.
- It resolves the steering repo's production branch to one commit and reads the server's folder at that commit.
- It imports the draft's source again, so the PR is built from the source and not from what Studio showed you.
- It builds the folder and runs the tool checks.
- It writes
server.toml,tools.toml,tools.lock.json, the vendored definition (openapi.yaml,schema.graphql, orproto/), andtests/calls.jsonlundertools/servers/<server>/, on the branchtools/<server>. - It records the PR on the draft.
A second Review adds one commit to the PR already open on tools/<server>. That commit holds only the files that differ from the branch. When the PR Review recorded is gone, Review opens a new one.
Review refuses while any imported tool has no risk, side_effect, or egress, so the PR never carries a tool a reviewer cannot judge.
What the PR body shows
- The imported, removed, and reclassified tools, the changed descriptions, and the saved tests.
- The tools whose result cap or paging changed, and the exposure mode when the draft changes it.
- The token total of every imported tool's definition against the budget, which is
definition_budgetinserver.tomlor the default. - The tool checks' findings, errors first, then warnings, then info.
Each list shows at most 200 tools. A body over 60,000 characters falls back to shorter lists, and then ends with a line that points to the Oxagen steering check.
When Review refuses
Each refusal answers conflict (409) unless the table says otherwise.
| Reason | What happened | What to do |
|---|---|---|
draft_not_found (404) | The server folder has no draft | Save a draft first |
draft_revision_stale | The stored draft is at another revision | Read the draft again, then Review |
draft_unchanged | The open PR or the production branch already holds every edit | Nothing to do |
tools_branch_moved | A commit landed on tools/<server> while Review built the folder | Review again |
tools_unclassified | An imported tool has no risk, side_effect, or egress | Classify the tool, save, and Review |
test_holds_credential | A saved test carries a credential header | Remove the header, save, and Review |
test_invalid | A saved test does not make one recorded exchange | Record the test again, save, and Review |
folder_invalid, definition_path_invalid | The folder does not validate or lock, or the definition names a file outside the folder | Fix the edit the message names |
server_toml_missing, server_toml_invalid, server_name_mismatch | server.toml is absent, does not parse, or names another server | Save a valid server.toml for this server |
source_required, source_invalid, importer_not_built | Review needs the source, the source does not import, or its importer has not shipped | Save the source again, or wait for the importer |
tool_not_offered, tool_not_found, tool_key_collision | The source does not offer an imported tool, an edit names an unknown tool, or two tools make one key | Remove or rename the edit the message names |
tool_paging_missing | A cap edit turns paging on for a tool whose definition has no paging pattern | Leave the tool's paging as it is, save, and Review |
production_branch_missing | The steering repo has no production branch | Restore the branch, then Review |
Add a server that runs on machines
A local command, or a registry package with source.machines, has no tools until a machine starts it. Review writes no lock that says a server offers nothing, so a machine lists the tools before Review. Add server in the app runs these steps for you.
| Capability | API route | What it does |
|---|---|---|
start_studio_listing | POST /v1/{org}/{ws}/tools/studio/listing/start | Asks a machine to list the draft's tools at a pin |
get_studio_listing | POST /v1/{org}/{ws}/tools/studio/listing/get | Reads the listing and, once it succeeds, the tools |
- Save the new server's
server.tomlwithsave_studio_draftatrevision: 0. Send no source. - Call
start_studio_listingwith the revision the save returned. A local command sendspin: the version it runs and the SHA-256 of the file the command resolves to on the machine. Runshasum -a 256on that file to read it. A registry package sends no pin, because Oxagen reads its SHA-256 from the public registry. Oxagen pins npm, PyPI, and NuGet packages. - Read
get_studio_listinguntilstatusissucceededorfailed. A machine you enrolled, in one of the server'ssource.machinesgroups, lists the tools the next time it polls Oxagen. It checks the pin before it starts anything. A listing starts a program before any review, so it never runs on another person's machine, andstart_studio_listingrefuses withmachine_not_yourswhen you enrolled none in those groups. - A listing that succeeds carries
tools: each tool the machine listed, with the classification Studio suggests. The listing saved the draft, so read it again, then save an import and a classification for each tool you want. - Call
open_studio_review. The folder's firsttools.lock.jsonpins what the machine checked.
A failed listing leaves the draft as it was. Fix the pin or the machine groups, save again at the revision you hold, and list again.
Servers in a private network
An environment whose network is relay:<name> sends each call through the relay of that name, which runs inside your network. A relay carries a request body of at most 8 MiB.
- Oxagen checks the body size of an approved call before it uses the approval. A body over 8 MiB fails the call, Oxagen sends nothing, and the approval stays unused. Call the tool again with a smaller body.
- Oxagen checks only a paged call's first page before it uses the approval. It builds each later page from the reply before it, so a later page over 8 MiB fails when Oxagen sends it.
- Oxagen measures a gRPC message only when it sends it, so an oversized gRPC call fails after it uses the approval.
Discover a server's tools
A source changes after you import it: a tool gains a parameter, another disappears, a registry package ships a new version. Discovery reads what the source offers now and compares it with the lock on the production branch. Three capabilities start a discovery and read what it found.
| Capability | API route | What it does |
|---|---|---|
start_studio_discovery | POST /v1/{org}/{ws}/tools/studio/discovery/start | Queues one discovery of one server folder |
get_studio_discovery | POST /v1/{org}/{ws}/tools/studio/discovery/get | Reads the latest discovery's status and outcome |
list_studio_tools | POST /v1/{org}/{ws}/tools/studio/tools/list | Lists the imported tools, then the offered tools no key imports |
An org Owner, or a workspace Admin or Member, can start a discovery, read it, and list the tools. A workspace API key acts as a Member, so it can call all three.
A discovery takes these steps:
- It reads
server.toml,tools.toml, andtools.lock.jsonon the production branch. - It reads the tools the source offers and writes each one to
mcp.tool_snapshots. - It builds a new lock and compares it with the served one.
- When an imported tool changed, or a registry package moved to a new version, it opens or updates one sync steering PR with the new lock.
- It records the outcome on the server's discovery.
Until the sync steering PR merges, the gateway withholds each tool whose input schema changed and each tool the new lock drops. A tool the source newly offers opens no PR. It shows on the Tools tab as available until you import it.
Poll get_studio_discovery while the status reads queued or running. A discovery ends succeeded or failed.
A local server, and a registry package that runs on machines, lists its tools on an enrolled machine. Its discovery reads waiting_for_machine until a machine in one of the server's source.machines groups polls Oxagen. That machine then lists the server's tools, and the discovery runs as any other. A discovery that waits for a machine is not stalled, and the hourly sweep leaves it alone. A run times out after 10 minutes and retries twice, and a failed run keeps the open PR and the withheld tools. A discovery that stays queued or running for over an hour reads stalled: true, and the hourly sweep asks for it again.
| Outcome | What it means |
|---|---|
unchanged | No imported tool changed, so the lock stands |
pr_opened | The discovery opened the sync steering PR |
pr_updated | The discovery added a commit to the open sync steering PR |
needs_digest | An OCI image that runs on machines has a newer version, and Oxagen cannot read the one hash the machine would check. A hash is a short code made from the content, and any change gives a different code. It records the version and opens no PR |
skipped | The schedule does not allow this run, or the new lock matches the one the open PR already proposes |
A registry package on machines from npm, PyPI, or NuGet moves to a new catalog version on its own. Oxagen reads the new version's hash from the public registry, the same way the machine reads it before it runs anything. A machine then lists the tools at that pin, and the sync steering PR moves source.version and shows the new hash in the lock.
A PyPI release holds one file per host, so its pin names one file: the release's universal wheel (py3-none-any), or its source distribution when it has none. The lock records that file's name and URL, the launch installs it with uvx --from <url>, and the machine hashes that file before it starts anything. A release with neither file cannot be pinned.
sync.schedule in server.toml decides which triggers run a discovery. start_studio_discovery and a merged sync steering PR always run one. A push to the steering repo runs one only for on-change. A changed tool list and a new registry version run one unless the schedule is manual. The hourly sweep runs one for a daily server whose last discovery is a day old, and once for an on-change server that has never finished one.
list_studio_tools suggests a classification for each available tool from what the snapshot keeps: the name, the description, the input schema, and the MCP hints. A snapshot keeps no request template, so an OpenAPI, GraphQL, or gRPC tool's suggestion falls back to fail_safe until you classify it. An available tool's token count is an estimate that leaves out the title and the output schema.
Read agent feedback
Open a tool on the server page. Its panel shows how agents used the tool over the last 30 days.
| Figure | What it counts |
|---|---|
| Calls | Calls that reached the tool check. A call denied by policy or parked for approval is left out. |
| Schema rejections | Calls the tool's input schema refused, or whose arguments Oxagen could not read. |
| Error results | Calls the tool ran and answered with an error. |
| Retries | Later calls to the tool in the same session, after one of the above. |
Below the figures, the panel lists what agents' reflections said about the tool, newest first. A high count of schema rejections or retries usually means the tool's description or input schema confuses agents. Draft a new description, and Review opens a steering PR for a person to check.
Oxagen counts only calls made through its served tools, from the day the count started. When the call store does not answer, the panel shows the counts as not recorded and still lists the notes.
Move connected servers into the steering repo
A workspace that connected MCP servers before it had a steering repo keeps them as rows in Oxagen. One migration steering PR moves them: a folder under tools/servers/ for each server, built from those rows and their pinned tool lists. When the PR merges, the next publish takes each server over. From then on, a change to the workspace's tools is a steering PR.
Oxagen opens the migration PR when a workspace's steering repo finishes its setup. To start a workspace that never started, or to retry one that failed, call migrate_tools_to_steering, or run oxagen tools migrate.
| Capability | API route | What it does |
|---|---|---|
migrate_tools_to_steering | POST /v1/{org}/{ws}/tools/steering/migrate | Opens the migration PR, or answers the one already open |
An org Owner or a workspace Admin can call it. A repeat call opens nothing new. It answers already_open with the open PR, or already_migrated once no server is left to move. A stdio server stays a row, and the PR body lists it with the reason.
Other writers of the folder
Oxagen's MCP server discovery also opens steering PRs under tools/. It uses the same writer as Review, so every tools steering PR follows the same branch rule, file limit, labels, and Oxagen steering check.
See External MCP servers for how served tools reach agents, and for the sources and credentials server.toml names.