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.
• 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 -->

(spec) => spec.categories

Then inspect one method:

<!-- prettier-ignore -->

(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 -->

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:

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.