runtype-admin

# Runtype Admin Use this skill for live account operations. Every mutation changes the user's Runtype workspace unless you run it against a disposable test account. ## Before you start Runtype has two hosted MCP servers. Both accept browser sign-in on the first call, or a Runtype API key sent as `Authorization: Bearer <key>`. | Server | URL | Tools | | ------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Standard MCP | `https://api.runtype.com/v1/mcp/protocol` | One named tool per operation, such as `get_me`, `list_agents`, and `list_runs` | | Code Mode MCP | `https://code.runtype.com/mcp` | `search`, `execute`, `get_platform_documentation`, `search_documentation`, `get_build_instructions`, `generate_persona_embed_code`, `get_persona_theme_reference` | To check which server is connected, look at the tool list. Code Mode lists only the seven tools in the table. Call `get_me` (on Code Mode, `execute` with `async (runtype) => runtype.getMe()`) to confirm the organization before you change anything. ## Operating rules - Read freely once you have identified the resource ID with a `list_*` or `get_*` call. - Write to a single resource only when the user asked for that change. Follow [Update resources safely](#update-resources-safely). - Use the `runtype-build-product` skill for builds that span several resources. - Get explicit confirmation before destructive, bulk, or hard-to-reverse actions. When you ask, state what else is removed and offer the reversible alternative: - `delete_product` removes the product's surfaces, surface items, and surface keys. It keeps the flows and agents. - `bulk_delete_records` and `delete_conversation` are irreversible. - `delete_schedule` also deletes the schedule's run history. Use `pause_schedule` instead. - `delete_messaging_conversation` deletes the transcript. Close the thread with `update_messaging_conversation` instead. - Never claim a mutation succeeded unless the tool result confirms it. - Never show secret values. Use metadata only. ## Standard MCP tools Discover before you act: - Identity and inventory: `get_me`, `list_products`, `list_agents`, `list_flows`, `list_tools`, `list_records`, `list_collections`, `list_skills`, `list_schedules`, `list_secrets`, `list_conversations`, `list_model_configs`, `list_model_configs_grouped`, `list_provider_keys`. - Debugging: `list_runs`, `trace_execution`, `trace_conversation`, `list_logs`, `get_log_stats`, `list_schedule_runs`, `get_record_results`, `get_record_step_results`, `get_record_costs`. - Validation: `validate_flow`, `validate_code`, `validate_product`, `validate_product_flow`, `validate_product_agent`, `validate_product_surface`, `validate_product_tool`. - Test runs: `execute_agent`, `run_flow`. - Evals and batches: `create_eval_suite`, `run_eval_suite`, `add_eval_cases`, `add_eval_case_from_execution`, `submit_eval`, `list_eval_batches`, `get_eval_results`, `compare_eval`, `compare_eval_record`, `analyze_eval_steps`, `submit_batch`, `get_batch_status`, `get_batch_summary`, `cancel_batch`. - Versions and releases: `list_flow_versions`, `get_published_flow_version`, `publish_flow_version`, `list_agent_versions`, `get_published_agent_version`, `publish_agent_version`, `list_agent_aliases`, `rollback_agent_alias`, `list_agent_deployments`. Surfaces belong to a product. List or change them with the product ID in hand. Use `list_model_configs` to see which models the account can run. `list_available_models` is the platform catalog: its `isEnabled` and `isDefault` fields are always null or false, so it cannot tell you whether a model is enabled. Large inventories (`list_products`, `list_agents`, `list_flows`, `list_tools`, `list_records`, `list_collections`, `list_skills`, and `list_schedules`) return compact string previews by default. Use that shape to find the resource, then call the matching `get_*` tool. Pass `view: "full"` only when you need complete strings across the whole page. `list_agents` also accepts `agent_type` (`runtype`, `external`, or `claude_managed`) when you know the type. ## Code Mode MCP Call `search` first when you are unsure which method to use: <!-- prettier-ignore --> ```js (spec) => spec.categories ``` Then inspect one method: <!-- prettier-ignore --> ```js (spec) => spec.methods.updateAgent ``` Call `execute` and shape the result inside the function. Filter, project, and aggregate before you return data, so large responses do not fill the context: <!-- prettier-ignore --> ```js async (runtype) => { const { data } = await runtype.listProducts({ limit: 20 }) return data.map((p) => ({ id: p.id, name: p.name })) } ``` Pass an arrow function with one parameter, such as `async (runtype) => ...`. Do not add a leading semicolon: the call fails with a syntax or validation error. ## Use the CLI Sign in with `runtype auth login`, or set `RUNTYPE_API_KEY`. The CLI calls either MCP server directly: ```bash runtype mcp tools runtype mcp call list_runs -F limit=20 --json runtype mcp call execute --server code -F code=@query.js --json ``` Use `-f key=value` for string values and `-F key=value` for JSON values. For log reads, `runtype logs list` and `runtype logs stats` take the same filters as `list_logs`, such as `--execution`, `--agent`, `--status`, and `--from`. ## Debug a failed run 1. Find the run with `list_runs`. Filter by `agent_id`, `flow_id`, `conversation_id`, `surface_id`, `record_id`, or `batch_execution_id`, and pass `status: "failed"`. Subagent and nested-flow runs fold under their parent in the unfiltered list. Pass `include_children` to list them flat. `list_runs` covers the last 24 hours unless you pass `from`. For a schedule, start with `list_schedule_runs`. 2. Pull the trace for that run: `trace_execution`, or `trace_conversation` for a multi-turn conversation. 3. Use `list_logs` after the trace. Filter by execution ID, conversation ID, level, status, or category. `list_logs` and `get_log_stats` search only the last 24 hours unless you pass `from` or `minutes_ago`. An empty result says nothing about older runs. 4. Inspect the referenced flow, agent, surface, tools, and secrets. 5. Validate the corrected payload. 6. Apply the smallest change. Re-run the same input with `execute_agent` or `run_flow`, then capture the case with `add_eval_case_from_execution` or `add_eval_cases`. Common causes: - A missing secret. Check with `check_secrets`. - A secret referenced in any form other than `{{secret:NAME}}`. `{{_internal.*}}` variables are blocked at runtime. - An unresolved template variable. - A tool schema that does not match the call. - A wrong surface behavior setting. - A model timeout. To stop a failing schedule, call `pause_schedule`. `run_schedule_now` counts toward the daily execution limit. ## Take over a messaging thread Messaging threads (Slack, iMessage, SMS, email, Telegram) are separate from assistant conversations. Their IDs start with `mconv_`, and `list_conversations` does not return them. 1. Find the thread with `list_messaging_conversations`. Filter by `surface_id`, `status`, or `agent_mode`. 2. Call `takeover_messaging_conversation`. If another operator took it over at the same time, the call returns 409 and names that operator. 3. Reply with `send_messaging_message`. 4. Call `resume_messaging_conversation` to hand the thread back to the agent. A takeover lapses after the surface's idle timeout (24 hours by default) without an operator reply. To start a fresh conversation on an SMS or iMessage surface, close the thread with `update_messaging_conversation`. Do not delete it. ## Update resources safely - Read the current configuration before you update it. - Keep fields that the request does not mention. - Validate before you update when a validator exists. - Follow pagination cursors on list tools. On `list_runs` and `list_logs`, stop paging when `pagination.cursorReset` is true: the response is page one again, and its cursor loops forever. - Use `get_platform_documentation` for exact contracts, such as schemas, routes, and the tool catalog (`topic="platform-catalog"`). Use `search_documentation` for how-to questions. On Code Mode, use `search` to find method signatures. - Use `get_platform_documentation(topic="dashboard-links")` when you give the user links. - Use `get_secret_intake_manifest`, `submit_secret_intake`, and `check_secrets` so that credential values never pass through the conversation. - When `get_tool`, `create_tool`, or `update_tool` returns `connection.status: "needs_connection"` for an OAuth2 MCP tool, give the user `connection.connectUrl` and ask them to click Connect. Call `get_tool` again to confirm `"connected"`. Never ask for OAuth tokens in chat. ## Roll back a change Before you change a flow or agent, note its published version with `get_published_flow_version` or `get_published_agent_version`. - Flow: find the earlier version with `list_flow_versions`, then publish it with `publish_flow_version`. - Agent: publish the earlier version with `publish_agent_version`. If the agent uses release aliases, call `rollback_agent_alias` and check the result with `list_agent_deployments`. A rollback restores configuration only. It does not undo messages sent, records written, or other external effects. Get explicit confirmation before you: - Set `on_conflict` to overwrite a flow or agent that is managed as code. Publishing rejects these by default. - Move the `live` alias. This needs the `AGENTS:DEPLOY:LIVE` permission and the alias's current revision as `if_match`. ## Handle permission errors On `Permission denied` (HTTP 403), do not retry with guessed IDs. Tell the user which permission is missing, or request a new key: 1. Call `request_api_key` with the narrowest `permissions` that cover the task and a specific `reason`. Keep the returned `codeVerifier`. It cannot be recovered. 2. Wait for a person to approve the request in the dashboard. 3. Redeem it with `runtype api-keys claim <request_id> --verifier <codeVerifier>`, or with `claim_api_key` using the default `delivery: "secret"`. Never print the key into the conversation. For deeper reference, load the `runtype` skill if it is installed. Prefer live MCP documentation over local files.