Skip to main content
The Ravenna MCP server provides tools covering ticket management, user administration, access control, workflows, analytics, and workspace configuration. Your AI client automatically discovers tool schemas and parameters when it connects to the server.
You do not need to memorize tool names or parameters. Your AI client discovers them automatically. This page helps you understand what is possible so you can ask your assistant the right questions.
Tool calls with unknown parameters are rejected. If your client sends a parameter that is not in a tool’s advertised input schema (for example, inventing assigneeIds on search_tickets), the call is rejected with an error naming the unrecognized keys and listing the accepted set. Nothing runs, so an invented filter cannot silently drop and return an unfiltered result set. Check the tool’s inputSchema and retry with the parameter names it advertises.

​
Tickets

Manage the full lifecycle of tickets in your workspace.

Get ticket by ID

Fetch full details for a specific ticket including messages, status, and metadata.
  • Review complete ticket history
  • Check current status and assignee
  • Retrieve custom field values
Create a new ticket with a title, description, and optional fields like priority, category, and assignee.
  • Log new requests from conversations
  • Create follow-up tickets from existing work
Attach the matching form. Call list_forms first to find the form that covers the request, and pass its id as requestTypeId. Put form field values in customFields (keyed by custom_field_id from list_forms or get_form), and workspace ticket attributes in attributeFields. The two are separate maps. Call get_form only when you need the option ids for a SELECT or MULTI_SELECT field.Only Published forms can be attached. Passing a requestTypeId whose form status is Draft or Archived is rejected with FORM_NOT_PUBLISHED and nothing is created. An id that does not exist in the current workspace is rejected with FORM_NOT_FOUND.unsetFields on the response. When the created ticket has no value for one or more of its form fields or workspace attributes, the response includes an unsetFields array. Each entry carries custom_field_id, label, type, required, and source ("form" or "attribute"). The field is advisory. The ticket is created regardless, and conditionally hidden fields and fields you lack permission to set are excluded. Fill any of the listed fields you have support for with update_ticket; leave the rest alone rather than guessing.
Modify ticket fields such as status, priority, assignee, category, or custom fields.
  • Reassign tickets during triage
  • Update priority based on new information
  • Change status as work progresses
  • Move a ticket to a channel in another workspace the caller belongs to
Setting queueId to a channel in another workspace triggers a cross-workspace move. The caller must be a member of the destination workspace (admin or member); otherwise the tool rejects the call. A cross-workspace move must be its own call: pass only id and queueId, with no other fields, files, or task template changes set. The move carries the ticket’s tags, category, and attributes into the destination by name (reusing destination rows where they exist and creating them where they don’t), re-points the status to the destination status of the same label (falling back to Open), and clears the form and parent link. See Move tickets for the full behavior.Switching the ticket’s form. Passing a new requestTypeId swaps the form on the ticket. The new form must be Published; a Draft or Archived form is rejected with FORM_NOT_PUBLISHED, and an id not in the workspace is rejected with FORM_NOT_FOUND. The guard only fires when the form is actually changing. A ticket already sitting on a form that has since been unpublished can still be updated without re-attaching it.
Perform across tickets to find relevant results by meaning, not just exact keywords.
  • Find related tickets when investigating an issue
  • Search across all ticket content including messages
Filter columns. Alongside priority, type, assigneeId, queueId, requestTypeId, requesterId, source, tags, createdAt, updatedAt, resolvedAt, and dueAt, the tool also filters on categoryId, parentId, approvalStatus, slaStatus, slaBreachingIn, csatScore, closedAt, respondedAt, snoozed, and archived. Filter by ticket status through the top-level status argument rather than a filter row.slaStatus and slaBreachingIn answer different questions. slaStatus is a finished outcome. Use it for tickets that already met or breached a target. slaBreachingIn is the at-risk filter: pass equals with a single positive number of minutes (for example, "60") to match tickets whose pending SLA target breaches within that window. Already-breached targets never match slaBreachingIn.Each filter is validated against its column’s vocabulary before the query runs. An unknown approvalStatus or slaStatus value, a non-numeric csatScore, an slaBreachingIn filter that is not equals with a single positive number, or a snoozed/archived filter that is not equals with "true" or "false" is rejected with a message listing the accepted values instead of returning an unfiltered result set. Archived and snoozed tickets are excluded unless you pass the corresponding filter.Filter by custom field value. Set column to attributeFields.<custom_field_id> to filter on a workspace , or customFields.<custom_field_id> to filter on a value captured by a form field. SELECT and MULTI_SELECT fields accept either the option id or the option’s display text as value. Use the wrong prefix and the tool returns an error naming the correct prefix for that field. Custom field filters require a specific workspace and are reported back on field_filters in the response, separately from the scalar filters array.
Example: filter by attribute and form field values
Given one source ticket, return that requester’s other tickets that are semantically similar to it. Use this to answer “has this person already filed this?” before creating a new ticket or during triage.
  • Detect duplicates for a specific ticket by id, short id, or display id (e.g. IT-42)
  • Tune how strict the match is with a similarity threshold (0-100)
  • Cap how many matches come back, most similar first
Results are scoped to the same requester as the source ticket. A source ticket with no requester returns no matches, and tickets without embeddings are skipped.
Retrieve child tickets linked to a parent ticket.
  • View sub-tasks of a larger project
  • Track progress across related work items

​
Ticket messages

Add and manage messages on tickets to track communication and progress. To read a ticket’s messages, use Get ticket by ID, which returns the conversation history alongside the ticket’s other details.
Add a new message to a ticket.
  • Post updates or status changes
  • Add internal notes for your team
  • Reply to requester questions
Add a private note to a ticket. Private notes are visible only to workspace members and admins; the requester never sees them.
  • Record internal observations, context, or next-step recommendations on a ticket
  • Reference the ticket by display ID (for example IT-42), short ID, or full ID
  • @mention a teammate by writing @[<userId>] or @[<email>] inline
The note is authored as the calling user. Available to workspace admins and members; guests cannot add private notes. See private notes for visibility rules.
Edit an existing message on a ticket.
  • Correct information in a previous update
  • Add additional context to a message

​
Ticket statuses

Define and manage the status options available for tickets in your workspace.
Retrieve all ticket statuses configured in the workspace.
  • View available status options for ticket updates
  • Audit your status workflow
Fetch details for a specific status.
  • Check status configuration and properties
Add a new status option to the workspace.
  • Extend your workflow with additional stages
  • Add custom statuses for specific processes
Modify an existing status, such as its name or order.
  • Rename statuses to match updated workflows
  • Reorder statuses in the pipeline
Remove a status from the workspace.
  • Clean up unused status options
  • Simplify your ticket workflow
Retrieve the number of tickets in each status.
  • Generate quick status reports
  • Monitor queue health and workload distribution
  • Identify bottlenecks in your workflow

​
Ticket tags

Organize and classify tickets with tags.
Search tags in the workspace by name, or retrieve the full list.
  • Find available tags before applying them
  • Audit tag usage across the workspace
Create a new tag for classifying tickets.
  • Add tags for new projects or initiatives
  • Create tags for specific issue types
Modify a tag’s name or properties.
  • Rename tags to match updated conventions
Create relationships between tickets and external resources.

​
Task items

Manage individual task items within tickets for granular work tracking. To view a ticket’s checklist, use Get ticket by ID, which returns its task items.
Retrieve task items assigned to the current user across the current workspace.
  • View your personal task list with linked ticket context (queue and ticket number)
  • Filter by completion status to focus on open work
  • Paginate through results for large task lists
Add a new task item to a ticket.
  • Break down tickets into actionable steps
  • Add checklist items during triage
Modify a task item, such as marking it complete or changing its description.
  • Track progress on individual steps
  • Update task details as requirements change
Deleting task items is not available over MCP. Remove them from the ticket in the Ravenna app.

​
Task templates

Create and manage reusable task templates that can be applied to tickets.
Retrieve all task templates in the workspace.
  • View available templates for common processes
  • Audit template usage
Fetch details for a specific task template including its items.
  • Review template content before applying
  • Check template configuration
Create a new task template with a set of predefined items.
  • Standardize processes like onboarding or incident response
  • Create checklists for recurring procedures
Modify an existing task template.
  • Add or remove items from a template
  • Update template names or descriptions

​
Categories

Manage the ticket categories the AI classifier assigns to incoming tickets. Each category has a name, an optional description, and example phrases the classifier reads to pick a category. Categories are flat, with no nesting. Exactly one category is the workspace default, used as the fallback when the classifier finds no better match.
Retrieve categories in the workspace, with each entry’s name, description, classifier examples, and whether it is the default.
  • Review how tickets are being classified
  • Look up a category ID before updating it
  • Filter by name with an optional case-insensitive substring search
Add a new category with a name, optional description, and example phrases. Names must be unique in the workspace (case-insensitive). The first category created in a workspace automatically becomes the default; after that, pass is_default: true to promote the new category and demote the current one.
  • Add a category for a new service area
  • Seed the classifier with example phrases users would send
  • Set a new fallback category for unmatched tickets
Change a category’s name, description, examples, or default status. Only the fields you pass are changed, and examples replaces the existing list wholesale, so include the phrases you want to keep. Setting is_default: true promotes this category and demotes the current default; is_default: false is rejected because a workspace always needs exactly one default.
  • Rename a category
  • Refine the description or example phrases to improve classification
  • Promote a different category to be the default
Delete a category by ID. The default category cannot be deleted; promote another category to be the default first.
  • Remove categories that are no longer relevant
  • Consolidate overlapping categories

​
Channels

Manage the channels (queues) where tickets are received and organized.
Retrieve all channels in the workspace.
  • View your channel structure
  • Find channels for ticket routing
  • Look up a destination channel in another workspace before a cross-workspace ticket move
By default the results come from the current workspace. To list channels in another workspace, pass targetWorkspaceId. The caller must be a member (admin or member) of that workspace; otherwise the tool rejects the call. This is intended for finding the destination of a cross-workspace ticket move. Omit it for everything else. Get workspace IDs from Get current user context rather than guessing.
Create a new channel for receiving tickets.
  • Set up channels for new teams or service areas
  • Create dedicated channels for specific ticket types
Modify channel settings such as name, description, or configuration.
  • Update channel details as team structures change
List the Slack channels available to connect to Ravenna: every channel the Ravenna Slack bot has been invited to, each marked with the Ravenna channel it already feeds.
  • Find candidate Slack channels before connecting one to a Ravenna channel
  • Check which Slack channels are already connected

​
Forms

Discover the forms available in the workspace, inspect the fields they capture, and build new ones. Use the read tools to pick the right form for a new ticket before calling create_ticket. Every form starts in Draft and is invisible to end users until you publish it with update_form. create_form accepts full form configuration and an ordered fields[] array in one call, so a typical authoring flow is: check list_forms for a name collision, call create_form with settings and fields, iterate with the field and reorder tools, then publish.
Deleting a whole form is not exposed over MCP. These tools can create, configure, publish, unpublish, and remove individual fields, but the destructive delete-form action is only available inside Ravenna Copilot. To retire a form, unpublish it with update_form (status: "Draft") and delete it from the Admin UI.
Retrieve every form and collection in the workspace with enough detail to pick the right one for a request and know what it will capture. Each form entry includes:
  • id: pass this as requestTypeId to create_ticket, update_ticket, and search_tickets.
  • name, description, and status (Draft, Published, or Archived). Only Published forms can be attached to a ticket.
  • isDefault: true when this is the workspace’s default form.
  • channels[]: the channels this form is attached to, as { id, name }. Use channels[].id as queueId on create_ticket. Empty means the form is not scoped to a channel.
  • defaultChannelId: the channel this form’s tickets land in by default, or null.
  • parentId: parent collection id, if any.
  • formEnabled: true when the form has custom fields.
  • fields[]: a per-field summary carrying the field’s id (used by another field’s parentId), custom_field_id (the key to use in customFields), name, description, type (TEXT, TEXT_AREA, SELECT, MULTI_SELECT, DATE, NUMBER, BOOLEAN, USER_SELECT, …), required, hidden, private, and conditional-visibility parentId and dependsOnValue.
Optionally filter by a search term. Call get_form only when you need the option ids for a SELECT or MULTI_SELECT field, or the form’s full usage counts.
  • Pick the form that matches a request before creating a ticket
  • Discover which fields a form will require so you can gather values in one turn
  • Find the queueId for a form-attached channel
  • Check for a name collision before calling create_form
  • Find the id of an existing form to update or add fields to
Fetch full detail for one form by id, including its ordered fields, every field’s option list and validation rules, each field’s id (RTCF join id) and private flag, and usage counts.
  • Look up the option ids for a SELECT or MULTI_SELECT field before filling it
  • Inspect a form’s full configuration when list_forms is not detailed enough
  • Read the current field order before calling reorder_form_fields
  • Look up a field’s RTCF id and private flag before calling remove_form_field
Create a new form with full configuration and an optional ordered fields[] array in one call. Covers name, description, icon/color/emoji, defaults (priority, channel, ticket type, task template), title template, audience targeting, tags, and assigned agents.
  • Author a complete intake form in a single call rather than create-then-update
  • Add top-level fields at creation; each field needs a label and type, and SELECT / MULTI_SELECT also need options
  • Nest inside a collection by passing parentId
Forms are created as Draft. Publish afterward with update_form (status: "Published").Conditional child fields (with parentId and dependsOnValue) are not created here. Add them afterward with create_form_field, referencing the parent field id returned by get_form.Title templates. Write placeholders as the field’s LABEL in double braces ({{Location}}), not a field key. The tool wires each placeholder to the field it creates. {{requester}} and {{requestType}} are always available. A placeholder that matches no field label renders empty and is reported back on partialApply so you can fix it with update_form.Audience. Set audienceType to Specific together with allowedGroupIds to restrict the form to certain user groups. Everyone and WorkspaceMembers ignore allowedGroupIds.Partial success. If the form is created but a follow-up step (nesting, a field, or the settings update) fails, the response includes a partialApply string describing what to retry with update_form or create_form_field. Do not re-call create_form, because the form already exists.
Update an existing form’s settings. Provide the form id and only the fields you are changing; omit the rest.
  • Publish a form by passing status: "Published", or unpublish back to editable with status: "Draft"
  • Change defaults (priority, channel, ticket type, status, task template) or the title template
  • Adjust visibility (audienceType, allowedGroupIds, isPrivate, featuredInPortal) and visual style (icon, color)
  • Reassign tags or agents
tags and agents replace the existing set, so send the full list you want, not just additions. Resolve ids first with search_tags, list_agents, list_user_groups, and search_task_templates.Use update_form only for existing forms; for field-level configuration like allow lists or source filters, use edit_form_field.
Create a collection (folder) that groups related forms. Pass a name, optional description, and optional parentId to nest it inside another collection.
  • Group related intake forms under one folder
  • Returns the collection id, which you pass as parentId to create_form or update_form to place a form inside
This creates a folder, not an intake form. Use create_form for an actual form.
Add a field to an existing form. Pass request_type_id, label, and type; SELECT and MULTI_SELECT require options.
  • Add fields that were not part of the initial create_form call
  • Add conditional child fields by passing a parent field id and dependsOnValue
  • Fields created here are private to the form by default
Modify an existing field on a form: label, type-specific configuration, allow list, source filters, and other field-level settings.
  • Rename a field or change its help text
  • Adjust allow lists or source filters
  • Update options on a SELECT or MULTI_SELECT
Attach a shared field (one whose definition already exists on another form) to this form.
  • Reuse a workspace-level field across multiple forms
  • Re-attach a shared field that was previously detached with remove_form_field
Fields created with create_form_field are private and cannot be re-attached after removal.
Remove a field from a form by its RTCF id (the id returned per field by get_form). There are two outcomes, so check the field’s private flag on get_form first:
  • Shared field (private: false): only the attachment to this form is removed. The field definition survives and stays on other forms. Reversible with attach_form_field.
  • Private field (private: true): the field definition is permanently deleted, along with any conditional child fields. Not reversible. Every field created with create_form_field is private, so this is the common case.
To remove a private field you must pass confirm_delete_private_field: true, or the call is rejected.
Reorder all top-level fields on a form in one call. Pass request_type_id and ordered_field_ids: the complete set of the form’s field RTCF ids (from get_form), in the desired top-to-bottom order.
  • Move a single field by reading the current order from get_form, repositioning that id, and sending the whole list back
  • Rearrange the entire form at once
A partial list, one with missing or duplicated ids or ids from other forms, is rejected, because leaving fields out would produce duplicate or ambiguous ordering.

​
Custom fields

Define custom data fields that can be added to ticket forms.
Retrieve all custom fields in the workspace.
  • View available fields for form configuration
  • Audit field usage across forms
Fetch details for a specific custom field.
  • Check field type, validation, and configuration
Create a standalone field in the workspace field library, attached to no form. The result is a shared field you can put on any form later with attach_form_field, and optionally register as a ticket attribute shown on every ticket.
  • Add a re-usable field once, then attach it to multiple forms
  • Create a ticket attribute in the same call by passing is_attribute: true
  • Prefer this over create_form_field when the field is not scoped to a single form
Provide label and type. SELECT and MULTI_SELECT require an options list. Entity-picker types (for example USER_SELECT, APPLICATION_SELECT, USER_GROUP_SELECT) are system-managed and do not take options; use allowList and, for user/group pickers, source to restrict the picker.Ticket attributes. Passing is_attribute: true also surfaces the field on every ticket in the workspace. Only TEXT, TEXT_AREA, DATE, DATETIME, BOOLEAN, SELECT, MULTI_SELECT, USER_SELECT, and USER_MULTI_SELECT are attribute-eligible; other types return an error. Set attribute values later via the attributeFields key on create_ticket / update_ticket.Requiredness is form-local and is not set here. Pass required when you attach the field to a form. Check list_custom_fields before calling to avoid a duplicate; re-use an existing field with attach_form_field if one already matches.
To edit or remove a field that is attached to a form, use edit_form_field and remove_form_field (see Forms). Updating or deleting a standalone workspace field is not available over MCP; manage those from Settings > Fields in the Ravenna app.

​
Custom field options

Read the selectable options for dropdown-type custom fields.
Retrieve all options for a custom field.
  • View available choices for a dropdown field

​
Snippets

Manage the reusable snippets agents insert into ticket replies.
Retrieve saved snippets in the workspace, with optional filters.
  • Find a saved response to insert into a ticket reply
  • Audit the snippet library
Save a response as a reusable snippet for future tickets.
  • Turn a well-written reply into a standard response
Revise an existing snippet.
  • Keep saved responses current as processes change

​
Reminders

Read and configure the workspace reminder policies that nudge pending approvers and ticket assignees on a recurring schedule. Each workspace has at most one policy of each type: APPROVAL (nudges pending approvers on an open approval round) and ASSIGNMENT (nudges the current assignee of an open ticket).
Both tools are admin-only. Callers without the workspace Admin role are rejected. The same policies power the Settings → Workspace → Automation UI, so changes here take effect immediately for all reminders in that workspace.
Read the current reminder policies for the workspace. A policy type absent from the results has no policy yet, so those reminders are off.
  • Check whether approval or assignment reminders are enabled before configuring them
  • Audit the interval, cap, business schedule, and conditions on each policy
Create or update a reminder policy for one type. Uses patch semantics: only the fields you pass change, the rest keep their current values. When creating a policy for the first time, enabled defaults to false and interval_hours to 24 unless you set them.
  • Turn approval or assignment reminders on or off
  • Adjust the interval, cap, or business schedule without touching other fields
  • Scope a policy to a subset of tickets with filter groups
Learn more about reminder policies, including how the interval, cap, business schedule, and conditions behave at fire time.

​
Platform

​
Users

Look up and manage user accounts in your organization.
Retrieve the profile of the authenticated user.
  • Verify your connection and identity
  • Check your own permissions and role
Retrieve all users in the organization.
  • Find users for ticket assignment
  • Generate user reports
  • Audit organization membership
Fetch details for a specific user by ID.
  • Look up a user’s profile, role, and group memberships
  • Verify user details for access requests
Modify a user’s profile or settings.
  • Update user roles or properties
  • Manage user account details
Create a new user in the organization and optionally add them to a workspace. Requires organization admin privileges.
  • Onboard new team members by creating their account and workspace membership in one step
  • Create user accounts without sending invitation emails for pre-provisioned setups
  • Add users to a specific workspace with a designated role (Guest, Member, or Admin)

​
User groups

Organize users into groups for permissions, assignment, and routing.
Retrieve all user groups in the organization.
  • View team structure and group organization
  • Find groups for routing rules
Fetch details for a specific group.
  • Check group configuration and membership count
Retrieve a group along with its full member list.
  • See who belongs to a specific team
  • Audit group membership for compliance
Create a new user group.
  • Set up groups for new teams or departments
  • Create groups for access control policies
Modify a group’s name, description, or membership.
  • Update group details as teams change
  • Add or remove members from a group

​
Organization members

View members of your organization with full user details.
Retrieve all organization members with full user profile details.
  • Generate organization-wide user reports
  • Audit who has access to the organization
  • Look up members across all workspaces

​
Workspaces

Manage the workspaces within your organization.
Fetch details for a specific workspace.
  • Check workspace configuration and settings
Modify workspace settings.
  • Update workspace name, description, or configuration
Slack emoji-action bindings are not part of this tool’s input. Use configure_slack_emoji_action (below) to change which emoji triggers a Ravenna action.

​
Business schedules

Manage the business schedules that define working hours for SLAs and reminders.
Retrieve business hour schedules for the workspace, including name, timezone, weekly hours, and holiday configuration.
  • Look up a schedule ID before attaching it to a reminder policy
  • Audit working hours and holidays
Create a business hour schedule with a name, IANA timezone, and weekly hours with time ranges per day.
  • Set up working hours for a new team or region
Update a schedule. Supports partial updates to name, timezone, weekly hours, holidays, or default status.
  • Adjust hours or holidays as they change
  • Promote a schedule to be the workspace default

​
Slack emoji actions

Read and remap the Slack emoji actions for the workspace: the reactions that create tickets, assign work, resolve tickets, and more when added to a Slack message.
Retrieve every configurable emoji action in the workspace. Each entry includes the action key, a human-readable label and description, the emoji shortcode and native character currently bound to it, the default shortcode, and whether the action is still on its default.
  • See which emoji currently triggers each action
  • Find custom bindings by checking isDefault
  • Get the exact action keys before calling configure_slack_emoji_action
Bind a Slack emoji to a Ravenna action, or reset the action to its default emoji. Pass an action key from list_slack_emoji_actions together with either an emoji or reset_to_default: true.
  • Remap an action to an emoji your team already uses
  • Restore an action to its default binding
The emoji value can be a native glyph (✅), a shortcode (white_check_mark, with or without colons), or a recognized alias. An unrecognized value is rejected with INVALID_EMOJI and nothing changes.Each emoji can map to only one action. Binding an emoji that already triggers another action is rejected with EMOJI_SHORTCODE_IN_USE, naming the conflicting action. Reset that action first or pick a different emoji.
Learn more about Slack emoji actions, including what each action does and who can trigger it.

​
Workspace members

View members of a specific workspace.
Retrieve all members of a workspace.
  • View who has access to a specific workspace
  • Audit workspace membership
Retrieve workspace members with full user profile data.
  • Generate workspace-specific user reports
  • Look up member details for assignment or routing

​
Applications

Manage the applications in your organization that users can request access to.
Search the application catalog with search_applications. Pass query to filter case-insensitively on name, display name, and domain (space-separated words must all match), or omit it to browse the whole catalog. Results come back in pages of 25 lean rows with total_count and has_more; pass the offset named in the response summary to fetch the next page.
  • Browse the access catalog before requesting or granting access
  • Find the application a request should target
  • Narrow to a single workspace’s catalog with workspace_id
  • Fetch full detail (ownership, notes, entitlement count) for up to 25 known applications per call with application_ids; IDs that don’t resolve come back in missing_ids rather than as an error
Archived applications are excluded unless you pass include_archived: true.Organization admins search the whole catalog. Everyone else’s search results include only applications available in a workspace they can reach, so an application missing from results may exist but be out of view.
Fetch a single application by ID, including its description and workspace associations.
  • Confirm which workspaces an application is available in
Add a new application to the catalog. Requires a name; optional fields include a description, workspaceIds to associate the application with specific workspaces, and archived status. The authenticated user is recorded as the creator.
  • Build out the access catalog for tools that are not synced from an identity provider
  • Stage a new application with its workspace associations before defining access levels
Modify an existing application’s name, description, workspace associations, or archived status.
  • Retire an application from the catalog by archiving it
  • Expand an application to another workspace
search_applications replaces the retired application__list. application__list is no longer MCP-enabled and now returns a stale-tool stub pointing at search_applications. External MCP clients calling the old name must migrate.

​
Access policies

Configure and manage access control policies for applications and resources.
Retrieve all access policies in the workspace.
  • View your access control configuration
  • Audit existing policies
Fetch details for a specific access policy.
  • Review policy rules and conditions
  • Check approval requirements
Define a new access policy for an application or resource.
  • Set up access controls for new applications
  • Create policies with approval workflows
Modify an existing access policy.
  • Adjust approval requirements
  • Update policy scope or conditions
Retrieve access levels a user is eligible for.
  • Show available options during access requests
  • Determine what a user can request
Retrieve applications a user is eligible to request access to.
  • Guide users to available applications
  • Filter access request options by eligibility

​
Access levels

Define and manage the specific permissions, roles, or entitlements that users can request within an application (for example, “Admin Access”, “Read-Only”, or “Developer Role”).
Retrieve access levels across all applications in the organization, optionally filtered by application.
  • Discover what access can be requested for a given application
  • Audit access levels across the organization
Create a new access level for an application by specifying the application, provisioning method, and optional approvers or access policy.
  • Define a new requestable permission such as “Admin Access” or “Viewer Role”
  • Link the access level to an approval policy at creation time
Modify an access level’s name, description, approvers, provisioning method, or associated access policy.
  • Adjust approvers or provisioning behavior for future requests
  • Rename or relink an access level without affecting existing entitlements

​
Access requests

Submit access requests on behalf of users.
Create an access request for an application on behalf of a user.
  • Submit requests programmatically as part of onboarding workflows
  • Request access on behalf of a new hire before their first day
  • Automate access provisioning based on role changes

​
Access entitlements

View and manage the access users currently hold across applications.
Retrieve access entitlements in the organization, with standard filter support.
  • Audit who holds which access levels
  • Build access reviews from current entitlements
Revoke one or more active entitlements by their IDs, with an optional revokeNote explaining the reason for the audit trail.
  • Pull access during offboarding or after an access review
  • Revoke several entitlements in a single call
Revocation is deferred: the provisioning workflow handles the actual de-provisioning asynchronously, so the entitlement moves through Deprovisioning before reaching Inactive. See Entitlements for the lifecycle.
Extend the expiration of one or more active entitlements. Pass an array of entitlement IDs and a duration in milliseconds to extend by.
  • Extend time-limited access before it expires
  • Renew access for several users in one call
Only applies to time-limited entitlements. Extension creates a new entitlement record linked to the original for lineage tracking.
Retrieve an overview of all access entitlements for the current user in the workspace.
  • Check what access you currently hold
  • Review your entitlements before requesting more access

​
Vault credentials

Read the credentials stored in the organization vault.
Retrieve all vault credentials for the organization. Returns metadata only; decrypted values are never exposed.
  • Audit which credentials are stored
  • Look up a credential before wiring it into provisioning

​
Approval templates

Create and manage reusable, multi-round approval workflows that can be applied across access requests, ticket escalations, change management, and other workflows requiring sign-off.
Retrieve approval templates in the organization, including each template’s rounds and approver configuration.
  • Find existing templates when configuring workflows
  • Review a template’s rounds and approvers before assigning it to a channel or policy
  • Audit approval processes across the organization
Define a new approval template with one or more rounds of approvers. Approvers can be specific users or groups, or dynamic options such as the requester’s manager.
  • Standardize multi-round approval workflows for reuse across the app
  • Provision templates programmatically as part of workspace setup
Modify the rounds or approver configuration on an existing template. Changes affect new workflows; in-flight approvals continue with their original configuration.
  • Adjust approvers as team structures change
  • Add or reorder rounds without rebuilding downstream workflows
Given a template ID, return the access policies that reference it, each with the access levels it governs.
  • Understand what a change affects before editing or retiring a template
  • An empty result means no access policy currently references the template

​
Automation

​
Code actions

Browse the automated code actions configured in your workspace. Authoring and publishing happen through Foundry, including the Foundry tools below.
Retrieve all code actions in the workspace.
  • View available automations
  • Audit existing code actions
Fetch details for a specific code action including its configuration and status.
  • Review action logic and settings
  • Check activation status

​
Foundry

Author Foundry integrations and actions from your AI client: connect an external API, generate action code against its documentation, test it, and publish it for agents and workflows to call.
Create and maintain the custom-API integrations that actions are built against.
  • list_foundry_integrations: list the workspace’s Foundry integrations with auth type, draft state, and docs-validation status
  • create_foundry_integration: create an integration shell from an API’s base URL, docs URL, and auth type
  • get_foundry_integration: check an integration’s draft state, docs-validation status, and whether credentials are stored
  • update_foundry_integration: change an existing integration’s name, URLs, auth type, or default headers
  • connect_foundry_integration: re-surface the authentication step for an integration that requires credentials
  • verify_foundry_integration_auth: make one authenticated read against the API to confirm stored credentials work
  • validate_foundry_docs: re-run documentation validation after fixing a docs URL
  • publish_foundry_integration: publish a draft integration so its actions can be dry-run and published
Credentials never travel through the conversation. They are entered through Ravenna’s secure connect flow and stored encrypted.
Let a Foundry action borrow credentials from a native Ravenna integration the organization has already connected.
  • list_native_bridge_integrations: list connected native integrations that can lend credentials to a Foundry action
  • set_action_native_bridge: re-link or unlink the native integration supplying an existing action’s credentials
Search the workspace’s Foundry actions by what they do, ranked by relevance.
  • Find an existing action that already covers a request before building a new one
  • Narrow by integration, or to published actions only
Create an action from a natural-language request, then generate its code.
  • create_foundry_action: create the action record against an integration, a native credential bridge, or as an internal Ravenna-data-only action
  • generate_foundry_action: generate the action’s code from the integration’s validated API documentation
Generation is asynchronous. Poll get_foundry_action for the settled generation status.
Fetch an action’s generation status, any generation error, last test status, published state, and input schema.
  • Poll while generation or iteration is running
  • Read the input parameters before testing or running the action
Test an action safely and revise it with natural-language feedback.
  • dry_run_foundry_action: run the non-mutating variant (live reads, mocked writes) and return the result, errors, and logs
  • iterate_foundry_action: hand feedback or a dry-run failure to Foundry’s code agent to revise the action
Publish a generated action so agents and workflows can call it. The backing integration must be published first.
  • Wire the published action to an agent rule as a tool, or into a workflow as a step
  • Publishing requires a completed generation, and a successful dry run is strongly recommended first
Running a published action directly is not available over MCP. Run it from the Foundry studio, or wire it to an agent or workflow.

​
Agents

Configure the AI agents that handle conversations, route requests, and automate work in your workspace.
Retrieve all AI agents in the workspace.
  • View available agents and their configuration
  • Audit agent deployment across channels
Fetch details for a specific agent including its capabilities, rules, and connected channels.
  • Review agent configuration before changes
  • Check which knowledge sources and tools are enabled
Create a new AI agent with a name, description, and initial configuration.
  • Stand up a new agent for a specific team or domain
  • Provision agents programmatically as part of onboarding
Modify an existing agent’s name, description, capabilities, or configuration.
  • Rename agents to reflect their scope
  • Update escalation instructions or capability settings
  • Adjust which channels an agent serves
Retrieve the tools that can be wired into agent rules, including integration tools and published Foundry actions.
  • Find a tool key before adding it to a rule’s tool list
  • Check what integrations your agents can act through
Learn more about configuring agents

​
Agent rules

Manage the natural language rules that define how your agents handle specific scenarios. Rules can be workspace-level (shared across agents) or attached to individual agents.
Retrieve all agent rules in the workspace, or rules attached to a specific agent. Pass a rule ID to get full detail for one rule (trigger, instruction, examples, tool wiring, execution policies, and attached agents) instead of the summary view.
  • Audit the rules powering your agents
  • Find rules that reference a specific form, workflow, or knowledge folder
  • Inspect a rule’s full configuration before editing it
Create a new agent rule with a title and natural language instruction. Optionally attach it to one or more agents.
  • Add a rule for a new kind of request your agents should handle
  • Bulk-author rules from external prompts or templates
Modify a rule’s title, instruction, or enabled state.
  • Iterate on rule wording to improve agent behavior
  • Disable a rule temporarily while debugging
Add an existing workspace-level rule to a specific agent.
  • Reuse a shared rule across multiple agents for consistent behavior
  • Roll out a new rule to selected agents only
Remove a rule from an agent without deleting the rule itself.
  • Stop an agent from using a shared rule while keeping it available for others
Learn more about writing agent rules

​
Knowledge bases

Discover the knowledge bases available to your agents.
List knowledge bases in the workspace, look them up by ID, or filter by name. Each result includes its document count and connected agents.
  • Find knowledge base IDs before connecting them to an agent
  • Check which agents a knowledge base already serves

​
Workflows

Plan, build, edit, and manage multi-step workflows directly from your AI client. These tools are consolidated, workflow-shaped operations designed for MCP agents. Start with plan_automation when the user describes an outcome in natural language, then create and configure the workflow with the tools below.

Plan automation

Turn a natural-language request (“close stale tickets after 14 days”) into a concrete workflow plan before anything is built. Returns a proposed trigger, step sequence, and any requirements that cannot be met so the user can confirm or adjust before create_workflow is called.
  • Route ambiguous “build me a workflow” requests through a single planning step
  • Surface gaps (missing integration, unsupported action) before drafting
Retrieve workflows in the workspace, with optional search by name and filter by state.
  • Find an existing workflow before editing
  • Audit which workflows are Draft, Active, Paused, or Archived
Fetch a single workflow’s full configuration including its steps, connections, trigger, and state.
  • Inspect a workflow’s current shape before editing
  • Pull step IDs needed by edit_workflow_step, remove_workflow_step, or configure_workflow_steps
Create a new workflow in Draft state with a name, description, trigger, and initial steps. Returns each new step with the input suggestions needed to configure it.
  • Draft a new workflow after plan_automation returns a confirmed plan
  • Scaffold workflows programmatically as part of onboarding
Update a workflow’s name or description. Metadata-only; does not touch the step graph, trigger, or state.
  • Rename a workflow to match a new process
  • Refresh a workflow’s description after its scope changes
Check whether a workflow is structurally valid and ready to go live. Returns validation issues (unresolved branches, disconnected steps, unconfigured inputs) instead of activating.
  • Verify a workflow after configuring every new step
  • Surface problems before asking a user to publish
Publish a workflow so it goes live and runs on its trigger. Call validate_workflow first: publishing a workflow with unresolved issues returns those issues instead of publishing, and a workflow that cannot be published from its current state comes back as published: false with the reason rather than an error.When republishing an active workflow that already has in-progress runs, the tool short-circuits and returns requires_decision alongside active_run_count. Ask the user whether those in-flight runs should finish on the previously published version (stop_active_runs: false) or be stopped so only the new version runs (stop_active_runs: true), then call publish_workflow again with the chosen value.
  • Take a Draft workflow live after validate_workflow returns clean
  • Republish a workflow after edits, deciding what happens to in-flight runs
Take a published workflow offline. Two modes:
  • mode: 'pause' stops accepting new runs but lets in-progress runs finish. The workflow shows as Paused and can be resumed later with publish_workflow.
  • mode: 'deactivate' unpublishes immediately and stops all in-progress runs. The workflow shows as Off.
Omit mode when the user has not decided. The tool then returns requires_decision with the in-progress run count so the agent can ask which mode to use. Pause is the less destructive default.
  • Pause an active workflow without cancelling in-flight runs
  • Unpublish a workflow and stop everything currently running
Duplicating and reverting workflows is not available over MCP. To reuse a workflow’s shape, call create_workflow and respecify the trigger, steps, and connections. Version rollback (previously “Revert workflow”) is not currently exposed over MCP.
Lifecycle tools replace the older tRPC-shaped MCP tools. workflow__update, workflow__run, workflow__retryWorkflowRun, workflow__pause, and workflow__deactivate are no longer MCP-enabled and now return stale-tool stubs pointing at their replacements (edit_workflow_info, run_workflow, retry_workflow_run, publish_workflow, and deactivate_workflow). External MCP clients calling those names must migrate. workflow__pause and workflow__deactivate also no longer accept bulk ids[]. Call deactivate_workflow once per workflow.

​
Workflow steps

Add, edit, and configure the individual steps that make up a workflow. Connections are managed implicitly by these tools. Pass source_id on add_workflow_step to chain a new step after an existing one, and remove_workflow_step reconnects around the removed step automatically.
Add one or more steps to an existing workflow. Pass source_id on each step to control where it attaches. Returns the created steps with input suggestions to feed into configure_workflow_steps.
  • Extend a workflow with additional logic
  • Insert a new action between existing steps
Update a step’s title, description, or swap its action for a different one. Requires workflow_id and step_id.
  • Swap a placeholder step for a real action
  • Change a step’s action without recreating it
Set input values and optional conditions on a single step. Use this to fix an individual step after a batch configure_workflow_steps call.
  • Correct one step’s inputs without touching the rest of the workflow
  • Add a conditional guard to a specific step
Configure inputs and conditions for multiple workflow steps in one call. Pass every step returned by create_workflow or add_workflow_step at once to avoid extra round-trips.
  • Fill in inputs for a freshly-created workflow in a single call
  • Apply a batch of edits during a workflow refactor
Add or update filters on a workflow’s trigger step. Narrows which events actually start a run (for example, only tickets in one channel or messages with a specific reaction).
  • Scope a trigger to a single channel or category
  • Match on a specific event property before starting a run
Remove a step from a workflow. Incoming and outgoing connections are re-attached automatically, so removing a middle step reconnects around it rather than orphaning downstream children.
  • Delete an unused or obsolete step
  • Simplify a workflow during refactoring
Duplicating steps and repositioning steps on the canvas is not available over MCP. Add fresh steps with add_workflow_step instead of duplicating. Layout changes (dragging steps to a new position on the canvas) are not exposed over MCP.

​
Workflow discovery

Discover the actions, triggers, and input options available when building or editing a workflow.
Retrieve every action available for use in a workflow, grouped by category (triggers, ticket actions, conditionals, wait/monitor, control flow, integrations).
  • Discover what integrations and actions are available
  • Find the right action name to pass to add_workflow_step
Fetch a single action’s details including its input schema, required fields, and validation rules.
  • Inspect an action’s inputs before adding it as a step
  • Check available options for a dropdown-typed input
Get input suggestions for a specific step: field types, literal options, and references to values from upstream steps. Returns referenceIds to pass to edit_workflow_step_input or configure_workflow_steps.
  • Look up how to reference a value from a previous step
  • Discover the available fields when configuring a step in a later turn
List the available filter fields, operators, and values for a trigger step.
  • Discover what a trigger can be filtered by before calling edit_workflow_trigger_filter

​
Workflow runs

Inspect workflow executions, trigger runs by hand, and retry finished runs.
Filter workflow runs across the workspace and page through the results, newest first.Filter parameters:
  • workflow_id: restrict to a single workflow.
  • statuses: array of run statuses. Use ["failed"] to find runs worth retrying.
  • created_after / created_before: ISO 8601 timestamps. Invalid timestamps return INVALID_DATE_RANGE rather than a generic database error.
  • limit: cap on runs returned. Defaults to 50, max 1000.
The response includes count (total runs matching the filter) and truncated (true when count exceeds the returned runs). Narrow the date range or raise limit before treating count as a definitive total.
  • Monitor recent runs of a specific workflow
  • Find failed runs in a time window for triage or bulk retry
Fetch a single run’s details including each step’s status, timing, inputs, outputs, and any errors.
  • Debug why a run failed
  • Trace the exact path a run took through a branching workflow
Trigger one run of a published workflow by hand, instead of waiting for its trigger to fire. The workflow must already be published; if it is not, the tool returns started: false and names publish_workflow rather than running anything.Pass inputs as an object keyed by field name to override the trigger payload the first step receives. The whole object is forwarded to the start step as-is. For a webhook-triggered workflow, nest the payload under body (and headers / query if the workflow reads them) so it matches the request shape the trigger expects. Omit inputs for a bare run.
Semantic change from the retired workflow__run. run_workflow forwards the whole inputs object as the start-step record. workflow__run accepted a fixed { headers, url, query, method, body } envelope. Callers migrating from workflow__run for a webhook trigger should move those fields into inputs ({ headers, query, body, ... }) rather than sending them at the top level.
The returned run_id goes to get_workflow_run_info to check how the run went.
  • Trigger a run manually for a workflow that normally fires on a webhook or schedule
  • Kick off a workflow with a specific payload for a one-off backfill or test
Start a new run from a finished one, usually a failure. The original run is left as it is; the new run_id is returned so you can inspect the retry with get_workflow_run_info.Options:
  • retry_from_failure: true: resume from the step that failed, reusing the successful steps’ outputs. Right for transient issues (rate limit, outage) where only the last step broke. Omit or set false to replay the whole workflow from the start.
  • use_latest_version: true: retry against the workflow as it is published now. This mirrors the “Retry with latest version” option in the web UI and is what you want after fixing a broken workflow. Omit or set false to replay the exact version the original run used; later edits are not picked up.
The response includes used_latest_version so callers can confirm which version the retry ran against. If the workflow has been edited since the original run and use_latest_version was not set, the message says so. If the workflow is not currently published and use_latest_version: true is set, the tool returns retried: false and points at publish_workflow.
  • Retry a failed run after fixing the workflow (use_latest_version: true)
  • Replay a failed run against its original version to reproduce a bug

​
Workflow collections

Organize workflows into collections for browsing in the Admin.
Retrieve every workflow collection in the workspace.
  • Find an existing collection before creating a new one
  • Audit how workflows are organized
Fetch a single collection’s details by ID.
  • Check a collection’s name and description
Create a new collection to organize workflows.
  • Group related workflows for a team or process area
  • Reuse an existing collection first by checking list_workflow_collections before creating one
Move a workflow into a collection, or pass null to remove it from its current collection. This is organizational only and does not affect the workflow’s behavior.
  • Reorganize workflows after a team change
  • Move a workflow into the collection its owning team browses

​
Analytics

Query analytics data and manage the dashboards and widgets that power your reporting. Use these tools to count, chart, or trend data over tickets, ticket messages, knowledge base documents, and workflow runs without paging through list results.

Query analytics chart

Run an analytics query and return aggregated, chart-ready data in a single call.
  • Count, group, or trend across tickets, ticket messages, knowledge base documents, or workflow runs
  • Pick a metric breakdown (“tickets by status”) or a time series (“ticket volume per day”)
  • Skip pagination through list tools when all you need is the aggregate
Retrieve the analytics dashboards and folders in the workspace with a compact summary of each dashboard’s widgets.
  • Find an existing dashboard before creating a new one
  • Decide where a new widget belongs based on existing topics
  • Search by name to narrow the list
  • Identify folders (entries with an item_type of collection) so you can file dashboards inside them
View a single dashboard’s widgets with freshly-computed data, layout, and re-runnable query specs.
  • Read the current numbers on a named dashboard
  • Inspect a widget’s spec to re-run or edit its query
Create a new, empty analytics dashboard, or a folder to group dashboards in. Optionally set a default date range and time interval.
  • Stand up a new reporting view for a team or initiative
  • Set the default view options every widget on the dashboard inherits
  • Create a folder by passing item_type: "collection"
  • File the new dashboard inside a folder by passing that folder’s id as parent_id
Modify a dashboard or folder’s name, description, or default view options (date range and time interval), or move it into or out of a folder.
  • Shift the reporting window for every widget on a dashboard at once
  • Rename or re-describe a dashboard as its purpose evolves
  • Move a dashboard into a folder by passing that folder’s id as parent_id
  • Move a dashboard back to the top level by passing parent_id: null
Save a chart or a ticket list as a persistent widget on an existing dashboard. For a chart, re-pass the same query parameters used with query_analytics_chart so the saved widget matches the previewed chart. For a ticket list, pass query_type: "table" with filters and the columns each row should show.
  • Pin a one-off chart for ongoing tracking
  • Build out a dashboard from a series of ad-hoc queries
  • Keep a live ticket list on a dashboard (for example, “add my open P1s to the dashboard”) without collapsing it into a count
Table widgetsUse query_type: "table" to save a Data card that lists individual tickets, one row per ticket, instead of an aggregate. Table widgets take filters, sort_by, sort_order, limit, and columns; they do not accept group_by, aggregation, chart_type, or time_interval.Pass columns as an ordered list of column references, left to right:
  • Built-ins: key, title, status, priority, assignee, requester, createdAt
  • A form field captured on the ticket: customField:<id>:<type> (look ids up with list_workspace_custom_fields)
  • A workspace ticket attribute: attributeField:<id>:<type> (look ids up with search_workspace_attributes)
Omit columns to save the widget with the default five: priority, key, status, title, requester. requester works as a column but is not sortable. Sort on createdAt, key, status, assignee, or a customField:<id> / attributeField:<id> reference (no :<type> suffix on sort).The tool returns a preview of the tickets the saved widget currently lists. Dashboard-level filters and date range apply at render time, so the live widget can show a different set.
Modify an existing widget: change its query, chart type, name, description, or (for table widgets) its columns and sort. Only the fields you pass change. Omit a field to leave it as-is.
  • Adjust a saved widget’s grouping or aggregation
  • Restyle a chart by passing just chart_type (no query_type needed)
  • Rename or re-describe widgets without recreating them
  • Change which columns a Data card shows, or re-sort its rows
Table widgetsTo change what a ticket-list widget shows, pass query_type: "table" together with the field you want to change (columns, filters, sort_by, sort_order, limit). Each field you pass replaces its saved value wholesale rather than merging, so read the widget’s current spec from get_dashboard and re-pass the full set you want the widget to end up with. Pass columns: [] to reset back to the default five columns. Table widgets have no chart_type.
Learn more about analytics dashboards
Learn more about setting up the MCP server
Last modified on September 17, 2026