Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Ravenna MCP Server create a high priority ticket for a login bug"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
This is a Model Context Protocol (MCP) server for the Ravenna help desk platform, allowing LLMs to create, update, and retrieve tickets directly from Ravenna.
Create tickets with title, description, priority, and tags
Update existing tickets (title, description, status, priority, etc.)
List tickets with various filters (status, priority, assignee, tags)
Get detailed information about specific tickets
Related MCP server: OTRS MCP Server
Clone the repository
Install dependencies:
npm install
# or
bun installSet your Ravenna API key as an environment variable:
export RAVENNA_API_KEY=your_api_key_herebun run index.ts
# or
npm run startThe server runs on stdio, making it compatible with MCP clients like Claude Desktop or other MCP-enabled applications.
Creates a new ticket in Ravenna.
Required fields:
title: The title of the ticket
description: A detailed description of the ticket
Optional fields:
priority: Ticket priority (low, medium, high, urgent)
tags: Array of string tags to categorize the ticket
Example:
{
"title": "Website login issue",
"description": "Users are unable to log in to the customer portal after the latest update.",
"priority": "high",
"tags": ["website", "login", "customer-portal"]
}Updates an existing ticket in Ravenna.
Required fields:
id: The ID of the ticket to update
Optional fields:
title: Updated title of the ticket
description: Updated description of the ticket
status: Updated status (open, in_progress, pending, resolved, closed)
priority: Updated priority (low, medium, high, urgent)
assignee: User ID to assign the ticket to
tags: Updated tags for the ticket
Example:
{
"id": "12345",
"status": "in_progress",
"assignee": "user_id_123",
"priority": "high"
}Lists tickets in Ravenna with optional filters.
Optional fields:
status: Filter by ticket status (open, in_progress, pending, resolved, closed, all)
priority: Filter by ticket priority (low, medium, high, urgent, all)
assignee: Filter by assignee user ID
tags: Filter by tags (any match)
limit: Maximum number of tickets to return
Example:
{
"status": "open",
"priority": "high",
"limit": 10
}Get detailed information about a specific ticket.
Required fields:
id: The ID of the ticket to retrieve
Example:
{
"id": "12345"
}This server uses the Ravenna API, as documented in https://docs.ravenna.ai/api-reference/.
This server implements the Model Context Protocol (MCP), making it compatible with MCP clients. It exposes tools that can be used by large language models to interact with Ravenna.
RAVENNA_API_KEY: Your Ravenna API key (required)
All tools include proper error handling and will return appropriate error messages if issues occur. Make sure your Ravenna API key is correctly set up and that you have the necessary permissions to perform operations.
Create a new ticket in Ravenna
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | The title of the ticket | |
| description | Yes | A detailed description of the ticket | |
| priority | No | Priority of the ticket (low, medium, high, urgent) | |
| tags | No | Tags to categorize the ticket |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, but the description adds no behavioral context such as side effects, required permissions, or return behavior for a creation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that efficiently states the purpose, though it could include more detail without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no output schema, and no explanation of return values or constraints, the description is insufficiently complete for an agent to fully understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description need not explain parameters; it adds no extra meaning beyond the schema, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new ticket in Ravenna' uses a specific verb and resource, clearly distinguishing it from sibling tools like get_ticket, list_tickets, and update_ticket.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use create_ticket versus alternatives, nor any prerequisites or conditions for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific ticket
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the ticket to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as read-only, non-destructive, idempotent. Description adds 'detailed information' but doesn't specify return format or any edge cases. Adequate given annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence, no unnecessary words. Could be slightly more precise about what 'detailed information' includes, but highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so description should hint at response structure. Does not mention that it returns full ticket details, fields like status, priority, etc. Missing for a simple retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (id) fully described in schema (100% coverage). Description repeats 'a specific ticket' but adds no new meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Get detailed information about a specific ticket', using a specific verb and resource. Distinguishes from siblings like list_tickets which returns multiple tickets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus list_tickets or how to obtain the ticket ID first. Implied usage from name, but no explicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tickets in Ravenna with optional filters
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Filter by ticket status | |
| priority | No | Filter by ticket priority | |
| assignee | No | Filter by assignee user ID | |
| tags | No | Filter by tags (any match) | |
| limit | No | Maximum number of tickets to return |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as read-only and idempotent. The description adds the 'Ravenna' context but otherwise restates the filter capability already in the schema. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words. Essential information (action, resource, context, filter capability) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks information about pagination, default ordering, or which fields are returned. However, the schema provides parameter descriptions, and annotations cover safety. It is adequate but not fully complete for a list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage for all 5 parameters. The description only repeats 'optional filters' without adding new meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'tickets', and the context 'in Ravenna', with optional filters. This distinguishes from sibling tools (create, get, update) which have different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for querying multiple tickets with filters, but does not explicitly compare to alternatives like get_ticket for single tickets or provide when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing ticket in Ravenna
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the ticket to update | |
| title | No | Updated title of the ticket | |
| description | No | Updated description of the ticket | |
| status | No | Updated status of the ticket | |
| priority | No | Updated priority of the ticket | |
| assignee | No | User ID to assign the ticket to | |
| tags | No | Updated tags for the ticket |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutability (readOnlyHint=false), but the description adds no additional behavioral context such as side effects, permissions, or error states. With annotations present, the bar is higher, and the description contributes little beyond the obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no unnecessary words. It is front-loaded with the core action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks critical context such as whether the update is a partial or full replacement (patch semantics), expected return value, or any side effects. Given the absence of an output schema, more context is needed for effective tool use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is documented in the schema. The description adds no extra meaning beyond what the schema provides, meeting the baseline for this dimension.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') and resource ('ticket'), and clearly distinguishes from sibling tools (create_ticket, get_ticket, list_tickets) which have different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when or when not to use this tool, nor any context about prerequisites or alternatives. The description simply states the action without usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.1.0create_ticketget_ticketlist_ticketsupdate_ticketScored across 4 tools
Each tool targets a distinct ticket action (create, get, list, update) with no overlap.
All tools follow a consistent verb_ticket pattern: create_ticket, get_ticket, list_tickets, update_ticket.
4 tools is a reasonable count for a focused ticket server, covering core operations without being excessive.
Basic CRUD is present but missing delete_ticket, which is a notable gap for ticket management.
Provides access to Civic Plus - See Click Fix, allowing you to interact with your data via an LLM.…
Connect AI tools to Weav customer service. Search conversations, reply, and manage knowledge.
Your workspace as agent tools — docs, canvases, slides, sheets, projects, tickets, and a shell.
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
