docs: consolidate MCP run-only access + cancellation tools, fix invented tool signatures (replaces #730, #733)

[jordanc-relevanceai]

Summary

Consolidates the two open PRs editing integrations/mcp/mcp-server.mdx, plus the MCP half of #716, into one change — and corrects every MCP tool signature on the page against the server's own tool-name registry and live tool schemas. Branched from main.

• integrations/mcp/mcp-server.mdx — OAuth consent and run-only access, roles and access levels, a rewritten execution workflow, a new Cancelling executions section, a new Running evaluations section, and an updated tool-access accordion.
• enterprise/rbac.mdx — Viewer row updated for MCP run-only access, personal API key row footnoted.

Replaces these PRs

PR	What it covered	Status
#733	MCP run-only access, Viewer role support, RBAC table updates	Folded in — closed
#730	Cancellation tools	Folded in with 3 parameter corrections — closed
#716	MCP tool table + relevance_run_evaluation	MCP half folded in, fully rewritten. Its evals-page half goes to the evals consolidation, so #716 is closed there

⚠️ Pre-existing errors on main, not just in the source PRs

This is the part worth your attention. The page already documented an MCP tool that does not exist, and #716 would have added a table repeating it.

main described two execution modes: relevance_trigger_agent as synchronous with a 120-second timeout, and relevance_trigger_agent_async for long runs. Checked against apps/nodeapi/src/mcp/tools/tool-names.ts, the server's canonical registry:

• There is no relevance_trigger_agent_async. The registry has triggerAgent: "relevance_trigger_agent" and pollAgentResult: "relevance_poll_agent_result" and nothing else for agent triggering.
• relevance_trigger_agent is already asynchronous. Its schema says it "Returns immediately with a conversation_id … does NOT wait for the agent to finish."
• There is no 120-second synchronous limit. The waiting happens on the poll side: relevance_poll_agent_result takes wait_seconds, default 50, max 300.

It appeared in four places on main — the Execution modes tabs, the timeout Warning, the workflow steps, and a Troubleshooting accordion that told people to switch to a tool that isn't there. All four are rewritten. The "Synchronous / Asynchronous" tabs are gone, since the distinction was fictional.

Also documented from the live schemas while I was in there: the real status values (in_progress, completed, failed, pending_approval) and the had_recoverable_tool_errors flag with its caveat.

Corrections to #730's cancellation parameters

All three were wrong, verified against the live tool schemas:

Documented	Actual
relevance_cancel_agent_task takes conversation_id	Parameter is task_id (the value is the conversation id)
relevance_cancel_workforce_task takes task_id	Requires both workforce_id and task_id
relevance_cancel_tool_run takes studio_run_id	Parameter is task_id; no studio_run_id exists

#730's behavioural claim was right and is kept: cancellation halts at the next step boundary, the in-flight step finishes, no hard abort.

Corrections to #716's relevance_run_evaluation table

Its three-row table had every row wrong:

• agent_id does not exist — the tool takes resource_id plus resource_type (agent or workforce).
• test_set_id is not required — it is mutually exclusive with scenario_ids.
• evaluation_run_name is required and was missing entirely.
• The claim that workforce evaluations "now correctly run against the version specified" is misleading: version_id pins the graph topology only, and nested agents still run their latest version. Documented as the caveat it is.

Carried over unverified

#733's run-only behaviour — the consent-page toggle, write/delete tools being absent rather than blocked, and the Viewer API-key minting footnote — is carried over as authored. I verified the tool registry and schemas, not the OAuth consent flow, so those claims still want a second pair of eyes.

I also reworded #733's "Viewer-role users can now connect… previously only Editor-role and above could connect" to state current behaviour, since the before/after framing reads as changelog copy in reference docs.

Test plan

• Mintlify preview renders the new auth subsections, both accordion groups, and both tables
• #oauth-consent-and-access-control resolves from rbac.mdx
• #cancelling-executions resolves from the Troubleshooting accordion
• grep -r trigger_agent_async returns nothing across the repo

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
relevanceai	🟢 Ready	View Preview	Jul 31, 2026, 7:05 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.