Skip to main content
Platform MCP exposes the AgentRuntime BFF as MCP tools so IDEs and AI assistants can list workflows, start runs, check analytics, and manage integrations — without crafting raw HTTP requests.
Endpointhttps://mcp.agentruntime.io/mcp
AuthPersonal access token (Bearer)
TransportStreamable HTTP (MCP)
Platform MCP is different from connector MCP instances used in workflow runs. Connector tools run at router.agentruntime.io during execution. Platform MCP drives the Console API from your IDE.

​
Quick setup (Cursor)

1

Create a PAT

In the Console, go to access token settings and create a PAT with scopes workflow:read, workflow:run, and mcp:execute as needed. Copy the token — it is shown once.
2

Add the MCP server

In Cursor, open MCP settings and add a remote server:
{
  "url": "https://mcp.agentruntime.io/mcp",
  "headers": {
    "Authorization": "Bearer pat_YOUR_TOKEN"
  }
}
3

Verify connection

Ask the assistant to call ar_health_summary or workflows_list to confirm the PAT resolves to your workspace.
The same URL and Bearer header work in Claude Code, OpenAI Codex CLI, and other MCP clients that support remote HTTP servers.

​
Authentication model

  • Send your PAT as Authorization: Bearer pat_... on every MCP request
  • The BFF infers tenant, project, and user from PAT introspection — do not set X-Tenant-Id manually
  • Your PAT must map to a user with the required project role (project_contributor for writes)

​
Tool groups

Tools are organized into groups. Production deployments may disable sensitive groups.
GroupToolsRisk level
coreWorkflows, runs, human tasks, analytics, healthStandard
catalogcatalog_bff_request — generic /v1/mcp/* passthroughStandard
memorySearch, episodes, propose/confirm itemsStandard
chatList conversations, send messagesStandard
filesWork file list and metadataStandard
websocketworkflows_stream_websocket — bounded WS readStandard
vaultList secrets; read/write with riskSensitive
patList/revoke; create/reveal with riskSensitive
inboundList/delete webhooks; create with riskSensitive
llm_keysCatalog; mutate/reveal with riskSensitive
Tools marked risk return secrets (vault values, PAT plaintext, webhook signing secrets, LLM API keys). These are hidden in production when the risk group is disabled.

​
Core tools (workflows and runs)

ToolBFF endpointPurpose
workflows_listGET /v1/workflowsList workflows
workflows_getGET /v1/workflows/{id}Get workflow graph
workflows_createPOST /v1/workflowsCreate draft
workflows_patchPATCH /v1/workflows/{id}Update draft
workflows_publish_versionPOST /v1/workflows/{id}/versionsPublish
workflows_validatePOST /v1/workflows/{id}/validateDry-run
workflows_execute_commandPOST /v1/workflows/{id}/commandStart/pause/resume/stop; response includes run_id (optional client run_id on start)
workflows_list_runsGET /v1/workflows/{id}/runsList runs (use when run_id is unknown)
runs_get_summaryGET /v1/workflows/{id}/runs/{run_id}/summaryPreferred run status read (orchestration_phase, session_id, run_complete)
runs_list_tenantGET /v1/runsTenant run feed
runs_list_eventsGET /v1/workflows/{id}/runs/{run_id}/eventsEvent log
runs_get_contextGET /v1/workflows/{id}/runs/{run_id}/contextRun variables

​
Human task tools (approvals)

Runs blocked on a human_task step stay running until a task is completed. Use these tools instead of inferring state from run events alone.
ToolBFF endpointPurpose
tasks_list_pendingGET /v1/tasks/pendingTenant-wide approval inbox
tasks_list_pending_runGET /v1/workflows/{id}/runs/{run_id}/tasks/pendingPending tasks for one run
tasks_completePOST /v1/workflows/{id}/runs/{run_id}/tasks/{task_id}/completeApprove or reject (approved: true|false)
After workflows_execute_command, save run_id from the response and poll runs_get_summary until the run completes, fails, or blocks. Call tasks_list_pending_run (or tasks_list_pending) to detect approval gates before reporting success.

​
Analytics tools

ToolMetric
analytics_live_runsCurrently active runs
analytics_success_rateSuccess percentage
analytics_credits_consumedCredits used
analytics_runs_timeseriesRuns over time
analytics_usage_timeseriesUsage over time

​
Catalog passthrough

catalog_bff_request is a generic tool for any /v1/mcp/* BFF route — list servers, create instances, validate bindings, list tools, and more. Pass method, path, optional query, and body. Example paths:
  • GET /v1/mcp/instances
  • POST /v1/mcp/instances/{id}/validate
  • GET /v1/mcp/platform-catalog
Paths containing /credentials require the risk group to be enabled.

​
Memory tools

ToolPurpose
memory_searchSemantic search over long-term memory
memory_get_episodeFetch an episode bundle
memory_get_continuationLatest open episode state
memory_propose_itemsPropose memory items
memory_confirm_itemConfirm an item

​
Live run streaming

workflows_stream_websocket opens a bounded WebSocket read on /v1/workflows/{workflow_id}/stream and returns collected frames. Defaults cap duration, message count, and total bytes to prevent runaway reads.

​
Example assistant prompts

  • “List my workflows and show the three most recent runs”
  • “Validate workflow {id} and start a run with params {\"env\": \"staging\"}”
  • “How many credits did my project consume this week?”
  • “Search memory for decisions about the Q2 pricing workflow”

​
Security practices

  • Use the minimum PAT scopes needed for your workflow
  • Prefer a dedicated PAT for IDE use — revoke it without affecting production automation
  • Do not enable risk tools unless you need vault, PAT, or credential management from the IDE
  • Rotate PATs if they appear in logs or shared configs

​
Local development

For local Platform MCP development, run the server from dev_tools/agentruntime-platform-mcp with: 
AGENTRUNTIME_BFF_URL=https://api-dev.agentruntime.io
AGENTRUNTIME_PAT=pat_...
Point your MCP client at http://127.0.0.1:8340/mcp (default local port).