> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axon402.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Two-Surface Migration

> How to move from mixed/admin IDE workflows to AXON's explicit runtime and operator/manage MCP surfaces

AXON now ships two explicit MCP surfaces:

* **Runtime** is the default story. It is for worker agents using a prepared wallet and the governed fetch / approval / receipt loop.
* **Operator/manage** is a separate advanced surface. It is for trusted developer and admin automation, and it requires an org-wide operator credential.

Use this guide if you are migrating an older IDE setup that mixed worker and admin actions under one MCP server entry.

> [!NOTE]
>
> **One key = one surface.** A wallet-scoped runtime key belongs on the runtime entry. An org-wide operator key belongs on the operator/manage entry. If a workflow needs both, mount both surfaces as two separately named MCP servers.

## Before you start

Before changing any config, figure out which surface each of your existing keys is already on. `GET /v1/me` returns a `surface` field that is authoritative:

```bash theme={null}
curl -s -H "Authorization: Bearer $AXON_API_KEY" $AXON_API_URL/v1/me | jq '.surface, .wallet_id'
```

| `surface` field | `wallet_id` | Meaning |
| :- | :- | :- |
| `"runtime"` | set | Wallet-scoped runtime key. Mount on the runtime entry. |
| `"operator"` | `null` | Org-wide operator key. Mount on the operator/manage entry. |
| `"operator"` | `null` (and `is_operator: true`) | Static operator key (`AXON_DECISION_API_KEY`). Operator entry only. |

The legacy "mixed" key shape no longer exists — every key currently in `api_keys` resolves to exactly one surface. If a key that used to drive control-plane actions still returns `surface: "runtime"`, that is the expected state: the key kept its wallet binding, and it can no longer mint wallets or move treasury. Mint a new operator key from the dashboard or `axon-op` for those workflows.

## What changed

Older setups often used one MCP server for everything:

* worker-agent spending
* approvals and receipt checks
* wallet creation
* treasury movement
* emergency freeze actions

That mixed model is no longer the product default. Keep the runtime surface narrow and let the operator/manage surface handle control-plane work.

## Migration map

| Old workflow | New workflow |
| - | - |
| One MCP server handled both `governed_fetch` and admin actions | Split into two MCP entries: runtime default + operator/manage advanced |
| Claude Code or Cursor used one key for all agent work | Use a wallet-scoped runtime key for the worker surface and an org-wide operator key for admin automation |
| OpenClaw scripts reached treasury or wallet actions from the same client that spent through a wallet | Keep OpenClaw on the runtime surface for spend; move admin operations to the operator surface or `axon-op` |
| IDE used to mint wallets, rotate keys, and run governed fetch in one config | Use the runtime surface for the agent and `@axon402/cli` / operator surface for admin tasks |

## Runtime-surface error remediation

If you send a wallet-scoped runtime key to a control-plane tool, AXON returns a runtime-surface error with code `TOOL_NOT_AVAILABLE_IN_RUNTIME_SURFACE` and `details.required_surface = "operator"`.

What that means:

* you are on the right product, but the wrong surface
* the request belongs on the operator/manage path
* the fix is to move the workflow, not to broaden the runtime key

Remediation:

1. Keep the worker-agent config on the runtime surface.
2. Move the admin action to the operator/manage surface or to `axon-op`.
3. Mint or reuse an org-wide operator key if the workflow needs MCP automation.
4. Retry the action on the correct surface.

Do not treat this as a reason to re-open the mixed default model.

## Step-by-step migration

If your current config has one MCP server driving both spend and admin work, take it in this order:

1. **Identify each credential's surface** with the `GET /v1/me` recipe above.
2. **Keep the runtime entry intact.** Your existing wallet-scoped runtime key continues to drive `governed_fetch`, approvals, and receipts on `POST /v1/mcp` (or stdio without `--surface=`).
3. **Mint an operator key** if admin work used to flow through the same MCP server. Dashboard → **Settings → API Keys → Create operator key**, or `axon-op keys create --name "<name>"` from the terminal with `--wallet` omitted. Never reuse a wallet-scoped key for control-plane work.
4. **Add a second MCP entry** named `axon-operator` (or similar) pointing at `https://api.axon402.com/v1/operator/mcp` or, if you self-host, `--surface=operator`. Paste from [IDE Setup → Advanced: Operator / manage surface](https://docs.axon402.com/docs/integrations/ide-setup.md#advanced-operator-manage-surface-opt-in).
5. **Verify the surfaces.** The runtime `tools/list` should return the runtime tools only, including provider-search tools on both hosted HTTP and self-hosted stdio runtime. The operator `tools/list` should return control-plane tools only: wallets, treasury, offers, API keys, mandates, approvals, ledger/earnings, and organization introspection. Any overlap means the wrong key landed on the wrong entry.
6. **Retire operator work from the runtime entry.** Remove any runtime-side scripts that call control-plane tool names — they will return `TOOL_NOT_AVAILABLE_IN_RUNTIME_SURFACE` on current builds.

If admin work can move off MCP entirely, prefer the dashboard or `axon-op`. Mount the operator/manage surface only when IDE-native automation is actually required.

## Operator/manage setup

The operator/manage surface is explicit and opt-in.

Recommended pattern:

* runtime server entry: default MCP server, wallet-scoped runtime key
* operator server entry: separate MCP server, org-wide operator key, `--surface=operator` or `/v1/operator/mcp`

If you need exact per-IDE examples, use [IDE Setup](https://docs.axon402.com/docs/integrations/ide-setup.md). That page contains ready-to-paste runtime and operator configs for Claude Code, Cursor, and generic MCP clients.

For terminal-first admin work, prefer [`@axon402/cli`](https://docs.axon402.com/docs/cli/installation#step-2-the-operator-cli) (`axon-op`) instead of mounting the operator/manage surface everywhere.

## Support guidance

When triaging a migration issue:

* Ask which surface the user is on.
* Check `GET /v1/me` and look at the `surface` field.
* If `surface = "runtime"` and the user is trying to manage wallets, treasury, or emergency controls, point them to the operator/manage setup.
* If a runtime key is hitting operator-only tools, tell them to move the action rather than broaden the runtime key.

Useful signals:

* `surface: "runtime"` means the credential is wallet-scoped.
* `surface: "operator"` means the credential is org-wide, static operator, or platform-session backed.
* `TOOL_NOT_AVAILABLE_IN_RUNTIME_SURFACE` means the request belongs on the operator/manage surface.

## Rollback posture

If migration needs to pause, keep the two surfaces separate.

* Do not revert to a mixed default surface. The product default stays runtime-only; the mixed model was a transitional accident, not a fallback.
* The `AXON_MCP_SURFACE_SPLIT_ENABLED` feature flag toggles the runtime-side enforcement of `TOOL_NOT_AVAILABLE_IN_RUNTIME_SURFACE`. Disabling it is a **rollback of enforcement**, not a revert of the product model — the runtime registry still ships the runtime-only tools, and operator work still belongs on the operator/manage surface.
* If a temporary compatibility bridge is truly required for a specific integration, treat it as a bounded, explicitly non-default path with an expiry date — never as the canonical way AXON is configured.

## FAQ

> **I had one key that did everything. Where did it go?**
>
> The key still exists and still authenticates. What changed is which tools are reachable with it. Run `GET /v1/me` — the `surface` field tells you whether it is a runtime (wallet-scoped) or operator (org-wide) credential today. If you need the other surface as well, mint a second key from the dashboard or `axon-op`; do not try to broaden the existing one.

> **Why can't my wallet-scoped key call `create_wallet` anymore?**
>
> Wallet creation, treasury movement, key rotation, offer mutations, and org-wide emergency stops are control-plane actions. They belong on the operator/manage surface with an org-wide operator key. Sending a wallet-scoped runtime key to these workflows returns `TOOL_NOT_AVAILABLE_IN_RUNTIME_SURFACE` with `details.required_surface = "operator"`. The fix is to move the workflow, not to escalate the runtime key.

> **Does every IDE need both entries?**
>
> No. Most worker agents only need the runtime entry. Add the operator/manage entry only when IDE-native admin automation is genuinely required. Day-to-day operator work belongs in the dashboard or `axon-op`.

> **Can I put both surfaces behind one MCP server name?**
>
> No. Mount them as **two separately named** MCP servers (e.g. `axon` + `axon-operator`). The stdio entrypoint dispatches on `--surface=`; the HTTP path uses `POST /v1/mcp` for runtime and `POST /v1/operator/mcp` for operator. Collapsing them recreates the mixed-surface confusion this split was designed to remove.

> **Will my existing automation stop working at cutover?**
>
> Anything already scoped correctly — runtime keys on runtime entrypoints, operator keys on operator entrypoints or `axon-op` — continues to work unchanged. The split tightens the runtime surface's rejection of control-plane tool names. If your automation depended on the legacy mixed default, use the step-by-step migration above to add an operator-surface entry.

## See also

* [IDE Setup](https://docs.axon402.com/docs/integrations/ide-setup.md)
* [MCP Server](https://docs.axon402.com/docs/integrations/mcp-server.md)
* [OpenClaw Plugin](https://docs.axon402.com/docs/integrations/openclaw-plugin.md)
* [GET /v1/me](https://docs.axon402.com/docs/api-reference/organizations/me.md)
* [API Keys](https://docs.axon402.com/docs/api-reference/organizations/create-api-key.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.