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:
(spec) => spec.categories
Then inspect one method:
(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:
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
- 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.
- Pull the trace for that run:
trace_execution, or trace_conversation for a
multi-turn conversation.
- 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.
- Inspect the referenced flow, agent, surface, tools, and secrets.
- Validate the corrected payload.
- 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.
- Find the thread with
list_messaging_conversations. Filter by surface_id, status,
or agent_mode.
- Call
takeover_messaging_conversation. If another operator took it over at the same
time, the call returns 409 and names that operator.
- Reply with
send_messaging_message.
- 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:
- Call
request_api_key with the narrowest permissions that cover the task and a
specific reason. Keep the returned codeVerifier. It cannot be recovered.
- Wait for a person to approve the request in the dashboard.
- 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.
1---2name: runtype-admin3description: 'Inspect, debug, or manage a live Runtype account through MCP or CLI; mutate only within the requested scope.'4user-invocable: true5argument-hint: '[live account operation or debugging task]'6metadata:7 source: https://skillmd.com/skills/hashgraph-online/runtype-admin8---910# Runtype Admin1112Use this skill for live account operations. Every mutation changes the user's Runtype13workspace unless you run it against a disposable test account.1415## Before you start1617Runtype has two hosted MCP servers. Both accept browser sign-in on the first call, or a18Runtype API key sent as `Authorization: Bearer <key>`.1920| Server | URL | Tools |21| ------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |22| Standard MCP | `https://api.runtype.com/v1/mcp/protocol` | One named tool per operation, such as `get_me`, `list_agents`, and `list_runs` |23| 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` |2425To check which server is connected, look at the tool list. Code Mode lists only the seven26tools in the table. Call `get_me` (on Code Mode, `execute` with27`async (runtype) => runtype.getMe()`) to confirm the organization before you change anything.2829## Operating rules3031- Read freely once you have identified the resource ID with a `list_*` or `get_*` call.32- Write to a single resource only when the user asked for that change. Follow33 [Update resources safely](#update-resources-safely).34- Use the `runtype-build-product` skill for builds that span several resources.35- Get explicit confirmation before destructive, bulk, or hard-to-reverse actions. When you36 ask, state what else is removed and offer the reversible alternative:37 - `delete_product` removes the product's surfaces, surface items, and surface keys. It38 keeps the flows and agents.39 - `bulk_delete_records` and `delete_conversation` are irreversible.40 - `delete_schedule` also deletes the schedule's run history. Use `pause_schedule` instead.41 - `delete_messaging_conversation` deletes the transcript. Close the thread with42 `update_messaging_conversation` instead.43- Never claim a mutation succeeded unless the tool result confirms it.44- Never show secret values. Use metadata only.4546## Standard MCP tools4748Discover before you act:4950- Identity and inventory: `get_me`, `list_products`, `list_agents`, `list_flows`,51 `list_tools`, `list_records`, `list_collections`, `list_skills`, `list_schedules`,52 `list_secrets`, `list_conversations`, `list_model_configs`, `list_model_configs_grouped`,53 `list_provider_keys`.54- Debugging: `list_runs`, `trace_execution`, `trace_conversation`, `list_logs`,55 `get_log_stats`, `list_schedule_runs`, `get_record_results`, `get_record_step_results`,56 `get_record_costs`.57- Validation: `validate_flow`, `validate_code`, `validate_product`,58 `validate_product_flow`, `validate_product_agent`, `validate_product_surface`,59 `validate_product_tool`.60- Test runs: `execute_agent`, `run_flow`.61- Evals and batches: `create_eval_suite`, `run_eval_suite`, `add_eval_cases`,62 `add_eval_case_from_execution`, `submit_eval`, `list_eval_batches`, `get_eval_results`,63 `compare_eval`, `compare_eval_record`, `analyze_eval_steps`, `submit_batch`,64 `get_batch_status`, `get_batch_summary`, `cancel_batch`.65- Versions and releases: `list_flow_versions`, `get_published_flow_version`,66 `publish_flow_version`, `list_agent_versions`, `get_published_agent_version`,67 `publish_agent_version`, `list_agent_aliases`, `rollback_agent_alias`,68 `list_agent_deployments`.6970Surfaces belong to a product. List or change them with the product ID in hand.7172Use `list_model_configs` to see which models the account can run. `list_available_models`73is the platform catalog: its `isEnabled` and `isDefault` fields are always null or false,74so it cannot tell you whether a model is enabled.7576Large inventories (`list_products`, `list_agents`, `list_flows`, `list_tools`,77`list_records`, `list_collections`, `list_skills`, and `list_schedules`) return compact78string previews by default. Use that shape to find the resource, then call the matching79`get_*` tool. Pass `view: "full"` only when you need complete strings across the whole80page. `list_agents` also accepts `agent_type` (`runtype`, `external`, or81`claude_managed`) when you know the type.8283## Code Mode MCP8485Call `search` first when you are unsure which method to use:8687<!-- prettier-ignore -->88```js89(spec) => spec.categories90```9192Then inspect one method:9394<!-- prettier-ignore -->95```js96(spec) => spec.methods.updateAgent97```9899Call `execute` and shape the result inside the function. Filter, project, and aggregate100before you return data, so large responses do not fill the context:101102<!-- prettier-ignore -->103```js104async (runtype) => {105 const { data } = await runtype.listProducts({ limit: 20 })106 return data.map((p) => ({ id: p.id, name: p.name }))107}108```109110Pass an arrow function with one parameter, such as `async (runtype) => ...`. Do not add a111leading semicolon: the call fails with a syntax or validation error.112113## Use the CLI114115Sign in with `runtype auth login`, or set `RUNTYPE_API_KEY`. The CLI calls either MCP116server directly:117118```bash119runtype mcp tools120runtype mcp call list_runs -F limit=20 --json121runtype mcp call execute --server code -F code=@query.js --json122```123124Use `-f key=value` for string values and `-F key=value` for JSON values. For log reads,125`runtype logs list` and `runtype logs stats` take the same filters as `list_logs`, such as126`--execution`, `--agent`, `--status`, and `--from`.127128## Debug a failed run1291301. Find the run with `list_runs`. Filter by `agent_id`, `flow_id`, `conversation_id`,131 `surface_id`, `record_id`, or `batch_execution_id`, and pass `status: "failed"`.132 Subagent and nested-flow runs fold under their parent in the unfiltered list. Pass133 `include_children` to list them flat. `list_runs` covers the last 24 hours unless you pass `from`. For a schedule, start134 with `list_schedule_runs`.1352. Pull the trace for that run: `trace_execution`, or `trace_conversation` for a136 multi-turn conversation.1373. Use `list_logs` after the trace. Filter by execution ID, conversation ID, level, status,138 or category. `list_logs` and `get_log_stats` search only the last 24 hours unless you139 pass `from` or `minutes_ago`. An empty result says nothing about older runs.1404. Inspect the referenced flow, agent, surface, tools, and secrets.1415. Validate the corrected payload.1426. Apply the smallest change. Re-run the same input with `execute_agent` or `run_flow`,143 then capture the case with `add_eval_case_from_execution` or `add_eval_cases`.144145Common causes:146147- A missing secret. Check with `check_secrets`.148- A secret referenced in any form other than `{{secret:NAME}}`. `{{_internal.*}}`149 variables are blocked at runtime.150- An unresolved template variable.151- A tool schema that does not match the call.152- A wrong surface behavior setting.153- A model timeout.154155To stop a failing schedule, call `pause_schedule`. `run_schedule_now` counts toward the156daily execution limit.157158## Take over a messaging thread159160Messaging threads (Slack, iMessage, SMS, email, Telegram) are separate from assistant161conversations. Their IDs start with `mconv_`, and `list_conversations` does not return162them.1631641. Find the thread with `list_messaging_conversations`. Filter by `surface_id`, `status`,165 or `agent_mode`.1662. Call `takeover_messaging_conversation`. If another operator took it over at the same167 time, the call returns 409 and names that operator.1683. Reply with `send_messaging_message`.1694. Call `resume_messaging_conversation` to hand the thread back to the agent.170171A takeover lapses after the surface's idle timeout (24 hours by default) without an172operator reply. To start a fresh conversation on an SMS or iMessage surface, close the173thread with `update_messaging_conversation`. Do not delete it.174175## Update resources safely176177- Read the current configuration before you update it.178- Keep fields that the request does not mention.179- Validate before you update when a validator exists.180- Follow pagination cursors on list tools. On `list_runs` and `list_logs`, stop paging when181 `pagination.cursorReset` is true: the response is page one again, and its cursor loops182 forever.183- Use `get_platform_documentation` for exact contracts, such as schemas, routes, and the184 tool catalog (`topic="platform-catalog"`). Use `search_documentation` for how-to185 questions. On Code Mode, use `search` to find method signatures.186- Use `get_platform_documentation(topic="dashboard-links")` when you give the user links.187- Use `get_secret_intake_manifest`, `submit_secret_intake`, and `check_secrets` so that188 credential values never pass through the conversation.189- When `get_tool`, `create_tool`, or `update_tool` returns `connection.status:190 "needs_connection"` for an OAuth2 MCP tool, give the user `connection.connectUrl` and ask191 them to click Connect. Call `get_tool` again to confirm `"connected"`. Never ask for OAuth192 tokens in chat.193194## Roll back a change195196Before you change a flow or agent, note its published version with197`get_published_flow_version` or `get_published_agent_version`.198199- Flow: find the earlier version with `list_flow_versions`, then publish it with200 `publish_flow_version`.201- Agent: publish the earlier version with `publish_agent_version`. If the agent uses202 release aliases, call `rollback_agent_alias` and check the result with203 `list_agent_deployments`.204205A rollback restores configuration only. It does not undo messages sent, records written,206or other external effects.207208Get explicit confirmation before you:209210- Set `on_conflict` to overwrite a flow or agent that is managed as code. Publishing211 rejects these by default.212- Move the `live` alias. This needs the `AGENTS:DEPLOY:LIVE` permission and the alias's213 current revision as `if_match`.214215## Handle permission errors216217On `Permission denied` (HTTP 403), do not retry with guessed IDs. Tell the user which218permission is missing, or request a new key:2192201. Call `request_api_key` with the narrowest `permissions` that cover the task and a221 specific `reason`. Keep the returned `codeVerifier`. It cannot be recovered.2222. Wait for a person to approve the request in the dashboard.2233. Redeem it with `runtype api-keys claim <request_id> --verifier <codeVerifier>`, or with224 `claim_api_key` using the default `delivery: "secret"`.225226Never print the key into the conversation.227228For deeper reference, load the `runtype` skill if it is installed. Prefer live MCP229documentation over local files.