oxagenDocs
MCP server

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.

CapabilityAPI routeWhat it does
save_studio_draftPOST /v1/{org}/{ws}/tools/studio/draftSaves the staged edits for one server folder
get_studio_draftPOST /v1/{org}/{ws}/tools/studio/draft/getReads the stored draft
open_studio_reviewPOST /v1/{org}/{ws}/tools/studio/reviewOpens 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/.

  1. 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 in server.toml.
  2. Send server.toml and the source the tools import from, such as an OpenAPI document, a GraphQL schema, .proto files, or an MCP server's tools/list result. Omit either one to keep the stored copy.
  3. Call save_studio_draft with the revision you started from.

The revision stops two tabs from overwriting each other:

  • revision: 0 starts a new draft. It never overwrites a stored one.
  • revision: N saves only when the stored draft is at N. Otherwise the save answers conflict with draft_revision_stale. Read the draft again with get_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.toml names a credential by reference only, as oxagen: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, or cookie header, with test_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-Key or ?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:

  1. It reads the draft and refuses when the stored revision differs from yours.
  2. It resolves the steering repo's production branch to one commit and reads the server's folder at that commit.
  3. It imports the draft's source again, so the PR is built from the source and not from what Studio showed you.
  4. It builds the folder and runs the tool checks.
  5. It writes server.toml, tools.toml, tools.lock.json, the vendored definition (openapi.yaml, schema.graphql, or proto/), and tests/calls.jsonl under tools/servers/<server>/, on the branch tools/<server>.
  6. 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_budget in server.toml or 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.

ReasonWhat happenedWhat to do
draft_not_found (404)The server folder has no draftSave a draft first
draft_revision_staleThe stored draft is at another revisionRead the draft again, then Review
draft_unchangedThe open PR or the production branch already holds every editNothing to do
tools_branch_movedA commit landed on tools/<server> while Review built the folderReview again
tools_unclassifiedAn imported tool has no risk, side_effect, or egressClassify the tool, save, and Review
test_holds_credentialA saved test carries a credential headerRemove the header, save, and Review
test_invalidA saved test does not make one recorded exchangeRecord the test again, save, and Review
folder_invalid, definition_path_invalidThe folder does not validate or lock, or the definition names a file outside the folderFix the edit the message names
server_toml_missing, server_toml_invalid, server_name_mismatchserver.toml is absent, does not parse, or names another serverSave a valid server.toml for this server
source_required, source_invalid, importer_not_builtReview needs the source, the source does not import, or its importer has not shippedSave the source again, or wait for the importer
tool_not_offered, tool_not_found, tool_key_collisionThe source does not offer an imported tool, an edit names an unknown tool, or two tools make one keyRemove or rename the edit the message names
tool_paging_missingA cap edit turns paging on for a tool whose definition has no paging patternLeave the tool's paging as it is, save, and Review
production_branch_missingThe steering repo has no production branchRestore 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.

CapabilityAPI routeWhat it does
start_studio_listingPOST /v1/{org}/{ws}/tools/studio/listing/startAsks a machine to list the draft's tools at a pin
get_studio_listingPOST /v1/{org}/{ws}/tools/studio/listing/getReads the listing and, once it succeeds, the tools
  1. Save the new server's server.toml with save_studio_draft at revision: 0. Send no source.
  2. Call start_studio_listing with the revision the save returned. A local command sends pin: the version it runs and the SHA-256 of the file the command resolves to on the machine. Run shasum -a 256 on 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.
  3. Read get_studio_listing until status is succeeded or failed. A machine you enrolled, in one of the server's source.machines groups, 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, and start_studio_listing refuses with machine_not_yours when you enrolled none in those groups.
  4. 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.
  5. Call open_studio_review. The folder's first tools.lock.json pins 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.

CapabilityAPI routeWhat it does
start_studio_discoveryPOST /v1/{org}/{ws}/tools/studio/discovery/startQueues one discovery of one server folder
get_studio_discoveryPOST /v1/{org}/{ws}/tools/studio/discovery/getReads the latest discovery's status and outcome
list_studio_toolsPOST /v1/{org}/{ws}/tools/studio/tools/listLists 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:

  1. It reads server.toml, tools.toml, and tools.lock.json on the production branch.
  2. It reads the tools the source offers and writes each one to mcp.tool_snapshots.
  3. It builds a new lock and compares it with the served one.
  4. 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.
  5. 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.

OutcomeWhat it means
unchangedNo imported tool changed, so the lock stands
pr_openedThe discovery opened the sync steering PR
pr_updatedThe discovery added a commit to the open sync steering PR
needs_digestAn 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
skippedThe 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.

FigureWhat it counts
CallsCalls that reached the tool check. A call denied by policy or parked for approval is left out.
Schema rejectionsCalls the tool's input schema refused, or whose arguments Oxagen could not read.
Error resultsCalls the tool ran and answered with an error.
RetriesLater 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.

CapabilityAPI routeWhat it does
migrate_tools_to_steeringPOST /v1/{org}/{ws}/tools/steering/migrateOpens 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.

On this page