mcp

MCP tools reference

When you connect an MCP client to roxels-mcp, the assistant gains a set of tools it can call. You don't call these directly — the assistant decides when, based on your conversation. This page lists what's available so you know what to ask for.

Templates

Manage and inspect the templates in your org.

Tool	What the assistant uses it for
`list_templates`	Show what templates exist in your org.
`get_template`	Read the full configuration of one template.
`create_template`	Author a new template from a natural-language description.
`update_template`	Modify goals, settings, outputs, phases.
`list_template_versions`	See the version history of a template.
`get_template_recent_sessions`	List the latest N conversations for a template.

Conversations

Inspect and orchestrate conversation runs.

Tool	What the assistant uses it for
`create_interview`	Start a server-side conversation against a template.
`list_interviews`	Show recent conversations, optionally filtered.
`get_interview`	Read transcript, findings, summary, and output deliveries for one conversation.
`get_session_diagnostics`	Surface latency, errors, and delivery details for one session.

Persons

Manage participants and their identity.

Tool	What the assistant uses it for
`list_persons`	List users tracked by your org.
`create_person`	Pre-register a participant with name and context.

Embeds

Set up the browser-side embed.

Tool	What the assistant uses it for
`list_embed_keys`	Show the embed keys for a template.
`create_embed_key`	Generate a new domain-allowlisted embed key.
`get_embed_code`	Produce the HTML snippet and init code for a template.

Outputs and integration

Configure how data leaves Roxels.

Tool	What the assistant uses it for
`get_integration_shape`	Read the current delivery proposal for a template (webhooks, frontend callbacks, chained API calls).
`revise_integration_shape`	Propose a change to the delivery shape.
`confirm_integration_shape`	Lock in the integration shape.
`update_webhook_schema`	Update the JSON Schema attached to a webhook output.

Skills and capabilities

Discover what the agent can do.

Tool	What the assistant uses it for
`list_skills`	List skills available in your org.
`list_skillsets`	List curated skill bundles.
`list_advisors`	List observer agents.
`list_archetypes`	List template archetypes and their prompt sections.
`list_data_sources`	List declared data sources for a template.

Quality and recommendations

The MCP's best feature — the assistant calls these to suggest concrete improvements.

Tool	What the assistant uses it for
`guided_setup_questions`	The most useful tool. Assess a template against best practices and real session data; return actionable recommendations.
`get_template_issues`	List coverage gaps and validation warnings on a template.
`get_runtime_learnings`	Read the learnings accumulated from webhook failures and other runtime signals.
`get_next_action`	Propose what to work on next, based on the state of your templates and recent sessions.

Discovery

Find out what's available.

Tool	What the assistant uses it for
`get_mcp_index`	Return the full catalog of MCP tools and their schemas. The assistant uses this to discover its own capabilities.

How the assistant decides what to call

You don't have to know these names. Ask the assistant in plain language:

"Show me my templates" → list_templates
"Why isn't the webhook firing?" → get_template_issues + get_template + maybe get_session_diagnostics
"What should I work on next?" → get_next_action
"Walk me through what's wrong with this template" → guided_setup_questions

If you're curious what tool the assistant just used, ask: "Which MCP tool did you call for that?" — it'll tell you.

Adding capabilities

When the Roxels backend adds a new tool, the MCP package gets a new version. Upgrade with:

pip install --upgrade roxels-mcp

The assistant can then call the new tool the next time it starts up.