MCP Server
Connect Claude Desktop, Cursor, and other MCP clients to Risotto to work with tickets, knowledge, runbooks, automation tools, access rules, and settings.
Risotto exposes a Model Context Protocol server so MCP-compatible clients (Claude Desktop, Cursor, ChatGPT, and custom agents) can call into your Risotto workspace. The server has 129 tools. You can work with tickets, knowledge, users, departments, runbooks, automation tools, access rules, campaigns, and organization settings. See Available tools for the full list.
To watch the setup and three examples of Claude at work, see the video Use Claude or ChatGPT with Risotto.
Clients authenticate with OAuth 2.1. Your client runs a standard browser-based authorization flow, and each user signs in with their own Risotto identity, so tool calls are attributed and audited per person. Claude Desktop, Claude Code, Cursor, ChatGPT, the MCP Inspector, and any client that ships a built-in OAuth UI connect this way, and Risotto refuses an API key from them. A headless client that can't complete a sign-in, such as a scheduled job, can send a Risotto API key instead. Every call appears in the request log.
Prerequisites
- A Risotto account in the organization. Every organization role can connect. Your role limits the scopes that you can grant (see Scopes and organization roles).
- An MCP-compatible client. OAuth requires a client that supports OAuth 2.1 + Dynamic Client Registration (Claude Desktop, recent Cursor, MCP Inspector, or any spec-compliant client).
Find your MCP server URL
Each Risotto organization has its own MCP server URL of the form:
https://api.tryrisotto.com/o/<org_id>/mcp
Copy your organization's specific URL from Settings → Developers → Risotto MCP server in the dashboard.
Connect with OAuth
Add the MCP server to your client
Most MCP clients only need the server URL — they handle registration and the consent flow automatically.
Edit your Claude Desktop config file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{ "mcpServers": { "risotto": { "transport": { "type": "http", "url": "YOUR_MCP_SERVER_URL" } } } }Replace
YOUR_MCP_SERVER_URLwith the URL from your dashboard. No client ID, client secret, or token URL is needed — Claude Desktop discovers everything from the server.Restart Claude Desktop after saving.
Open Cursor Settings → MCP → Add MCP server and paste your MCP server URL from the dashboard.
Save. Cursor will trigger the OAuth flow on first use.
ChatGPT connects to Risotto as a custom MCP connector.
In ChatGPT, go to Settings → Connectors → Add custom connector and paste your MCP server URL from the dashboard.
ChatGPT runs the OAuth flow automatically — sign in with your Risotto account and approve the scopes you want. Risotto's tools then appear in ChatGPT's tool picker.
npx @modelcontextprotocol/inspector YOUR_MCP_SERVER_URLThe Inspector opens a browser tab for consent, then exposes a JSON-RPC console for poking at the server directly.
- macOS:
Sign in and grant scopes
The first time the client connects, a browser tab opens to a Risotto consent screen. Sign in with the same account you use for the dashboard and review the scopes the client is requesting. Clear the checkbox next to a scope to leave it out of the grant, then click Allow.
The scopes you approve at this screen bound that specific client's access. They don't change your overall account permissions. The screen lists only the requested scopes that your organization role can hold. Each user makes this choice for their own connection. An admin cannot limit which scopes the users in the organization grant.
When an admin adds Risotto as a connector for the whole organization (for example, in Claude's organization settings), the consent screen does not open. Each user sees it the first time they connect to Risotto from their own client.
Use the tools
Risotto's tools now appear in the client's tool picker. The access token issued at consent is refreshed automatically; you won't be re-prompted unless you revoke the client or the refresh window lapses.
Available scopes
OAuth clients request scopes at consent time. A scope grants the tools listed under it in Available tools.
| Scope | Grants |
|---|---|
tickets:read | List and read tickets, comments, ticket insights, and ticket field definitions |
tickets:write | Create, update, resolve, and escalate tickets, and add comments |
tickets:delete | Reserved. No MCP tool uses this scope yet |
knowledge:read | Search indexed knowledge, list knowledge sources, check a document's index |
users:read | Find users and read their profiles and groups |
departments:read | List departments (ID and name only without config:read) |
departments:write | Create departments and change department settings |
runbooks:read | Read runbooks and a ticket's runbook history |
runbooks:write | Create, update, duplicate, and delete runbooks and forms, and read drafts, revisions, templates, forms, and the authoring guide |
tools:read | List automation tools and tool templates, read script drafts and runs |
tools:write | Create and update automation tools and script tools, set tool approval |
tools:execute | Run and test automation tools and scripts |
custom_api_sources:read | List custom API sources and browse the shipped API templates |
custom_api_sources:write | Create custom API sources and stage, test, and promote endpoint drafts |
external_mcp_servers:read | List connected external MCP servers |
external_mcp_servers:write | Connect external MCP servers and import their tools |
applications:read | List the applications that requestors can ask access to |
access_rules:read | List access rules |
access_rules:write | Create and update applications and access rules |
settings:read | Read organization settings, request sources, and the IdP config |
settings:write | Update organization settings, request routing, ticket fields, and Okta config |
artifacts:read | List and read artifact pages |
artifacts:write | Create, update, and delete artifact pages |
audit:read | Read the configuration audit log |
campaigns:read | List campaigns and read their recipients and submitted responses |
alerts:read | List the open error and warning alerts from the last 14 days, the same alerts as the Alerts page |
categories:read | List the ticket categories of a department |
categories:write | Create and update the ticket categories of a department, and read the category authoring guide |
config:read | Read Assistant settings, full department settings, and the automation opportunities report |
config:write | Update Assistant settings |
triggers:read | Reserved. No MCP tool uses this scope yet |
triggers:write | Reserved. No MCP tool uses this scope yet |
Scopes and organization roles
Your organization role limits the scopes that a client can hold:
- Org Admin and Org Manager can hold every scope.
- Member can hold
tickets:read,tickets:write,knowledge:read,users:read,departments:read,runbooks:read,categories:read,applications:read,tools:read, andtools:execute. A Member can run and test only the tools of the departments that they supervise. A Member cannot holdcategories:write. A department Supervisor changes categories with the dashboard Assistant or on the Categories page.
At consent, a Member sees only the requested scopes in this list. If none of the requested scopes is in the list, the client gets access_denied. Risotto checks the role on every request. When an admin changes your role, your tokens get the scopes of the new role within 5 minutes. A user who leaves the organization gets 403.
A Member also has these limits:
- A Member can act only as themselves. Risotto refuses a
create_ticketfor another requestor ("You can create tickets only for yourself"), anadd_commentas another author ("You can comment only as yourself"), and asearch_knowledgeorcheck_document_index_statuson behalf of another user ("You can search only with your own access"). search_knowledgewith adept_idworks only for a department where the Member can read tickets. Withoutdept_id, it searches only documents shared with the whole organization.list_runbooksandget_runbookreturn the org-wide runbooks and the runbooks of the Member's departments.
Manage authorized clients
From Settings → Developers → Risotto MCP server in the dashboard you can:
- See every OAuth client that has registered against your organization, including the IP it was registered from and when it last made a request.
- Revoke a client — invalidates all of its tokens immediately. The client will be prompted to sign in again on its next request.
Revoking an OAuth client only affects that one client. Other authorized clients keep working.
Available tools
The server registers 129 tools. Each tool needs one scope. tools/list returns only the tools whose scope your credential holds, with their input schemas. For example, a Member sees only the tools of the Member scopes, and an API key with narrow scopes sees only the tools of those scopes. Risotto also checks the scope when you call a tool, so a call to a tool outside your granted scopes fails with a missing-scope error.
Tool names below are the values you pass in tools/call. The dashboard Assistant is built on the same tools.
Where a ticket tool takes a ticket_id, you can pass the Risotto key (for example IT-123) or the key of the synced ticket in your ticketing system (for example the Jira key ENG-123). Risotto tries the Risotto key first, then the synced key. If more than one ticket has the same synced key, Risotto uses the newest ticket. Ticket results include external_ticket_id and external_ticket_url. Both are null when the ticket is not synced. list_tickets has no filter for the synced key, but its search argument matches the synced key.
Ticket results also include priority, as { value, is_suggested } or null. value is low, medium, high, or urgent. is_suggested is true when the value is the priority that the AI suggested, and false when a person set it. The ticket tools cannot change the priority. See Ticket priority.
To find tickets about a topic, pass search to list_tickets. The search is not case-sensitive. It matches the ticket title, public comments, the requestor's email, the assignee's name, the name of the Slack channel where the ticket started, the synced key, and the ticket number (123 or IT-123). Risotto combines search with the other filters. The dashboard Search tickets box matches the same fields.
Tickets and comments (8 tools)
| Tool | What it does | Scope |
|---|---|---|
list_tickets | List, filter, and search tickets. Returns up to 100 tickets per page. | tickets:read |
get_ticket | Get one ticket with its comments and workflow state. | tickets:read |
list_ticket_comments | List the comments on a ticket. | tickets:read |
create_ticket | Create a ticket. The agent processes it like a ticket from chat. | tickets:write |
update_ticket | Update ticket fields. Only the fields you pass change. | tickets:write |
add_comment | Add a comment to a ticket. | tickets:write |
resolve_ticket | Mark a ticket as resolved. Also resolves the synced external ticket. | tickets:write |
escalate_ticket | Escalate a ticket to human support. Sends a Slack notification and stops the agent. | tickets:write |
Ticket insights (7 tools)
| Tool | What it does | Scope |
|---|---|---|
get_ticket_runbook_match_history | Show which runbooks matched a ticket and why. | tickets:read |
get_ticket_retrieval_history | Show the knowledge that Risotto retrieved for a ticket. | tickets:read |
get_ticket_agent_activity | Show the agent's steps on a ticket in order. | tickets:read |
list_ticket_runbook_history | List the runbooks matched to a ticket and whether the agent followed them. | runbooks:read |
get_automation_opportunities | Report the requests Risotto could still automate, ranked by ticket volume. Also needs tickets:read. | config:read |
list_ticket_custom_fields | List the additional ticket fields defined for the organization. | tickets:read |
create_ticket_custom_field | Create an additional ticket field in a department. | settings:write |
Knowledge (4 tools)
| Tool | What it does | Scope |
|---|---|---|
search_knowledge | Search indexed knowledge with semantic and keyword retrieval. | knowledge:read |
list_knowledge_sources | List the connected knowledge sources and their index IDs. | knowledge:read |
check_document_index_status | Check whether a document is in the index, by URL or title. | knowledge:read |
get_knowledge_gap_report | Read the latest saved knowledge gap findings for the departments whose tickets you can read. It does not start a new report. | knowledge:read |
Users (3 tools)
| Tool | What it does | Scope |
|---|---|---|
find_users | Search users by name or email. | users:read |
get_user_profile | Get a user's profile from the identity provider. | users:read |
get_user_groups | Get the identity provider groups a user belongs to. | users:read |
Departments and Tier 2 Assistant (14 tools)
| Tool | What it does | Scope |
|---|---|---|
list_departments | List departments with descriptions, ticket prefixes, and member counts. Without config:read, returns only the ID and name. | departments:read |
get_department | Read every setting of one department. Without config:read, returns only the ID and name. | departments:read |
create_department | Create a department from a name and a description. | departments:write |
update_department_setting | Set one department setting, such as the name or description. | departments:write |
update_department_ticket_sync_setting | Set one Ticket Sync toggle for the department's external ticketing system. | departments:write |
set_department_ticket_prefix | Set the ticket prefix, for example IT in IT-123. | departments:write |
set_department_agent_channel | Set the Slack channel where Risotto posts escalations for the department. | departments:write |
set_department_escalation_contact | Set the person Risotto notifies when a ticket escalates. | departments:write |
list_department_categories | List a department's ticket categories, including inactive ones. A sub-department returns its parent's categories. | categories:read |
create_department_category | Add a ticket category to a department. A description is required. Refuses a name that differs from an existing category only by case or spaces. | categories:write |
update_department_category | Change a category's name, description, display order, or active state. Omitted fields stay unchanged. To remove a category, set is_active to false. There is no delete tool. | categories:write |
get_category_authoring_guide | Get the guidelines for writing and changing categories, as Markdown. | categories:write |
get_tier_2_assistant_config | Read a department's Assistant settings: auto start and the investigation and execution instructions. | config:read |
update_tier_2_assistant_config | Set a department's Assistant auto start, investigation instructions, or execution instructions. Omitted settings stay unchanged. | config:write |
Runbooks, templates, and forms (17 tools)
| Tool | What it does | Scope |
|---|---|---|
list_runbooks | List and filter runbooks. | runbooks:read |
get_runbook | Get a runbook's current version: conditions, instructions, and tool references. | runbooks:read |
get_runbook_draft | Get a runbook's pending draft revision. | runbooks:write |
list_runbook_revisions | List every version of a runbook, newest first. | runbooks:write |
get_runbook_authoring_guide | Get the runbook authoring guide as Markdown. | runbooks:write |
create_runbook | Create a runbook. It is active and indexed immediately. | runbooks:write |
update_runbook | Update one or more fields on a runbook. | runbooks:write |
upsert_runbook_draft | Stage or replace a pending draft revision on a runbook. | runbooks:write |
duplicate_runbook | Copy a runbook. The copy starts disabled with " (Copy)" in its title. | runbooks:write |
delete_runbook | Soft-delete a runbook. The version history is kept. | runbooks:write |
list_runbook_templates | List the curated runbook templates and whether your tools are ready for them. | runbooks:write |
get_runbook_template | Get a runbook template with its content. | runbooks:write |
list_forms | List the structured-input forms, newest first. | runbooks:write |
get_form | Get a form's fields and the runbooks that reference it. | runbooks:write |
create_form | Create a form for runbooks to collect answers from requestors. | runbooks:write |
update_form | Update a form. Omitted arguments stay unchanged. | runbooks:write |
delete_form | Delete a form. | runbooks:write |
Automation tools and scripts (16 tools)
| Tool | What it does | Scope |
|---|---|---|
list_tools | List the organization's automation tools with their parameter schemas. | tools:read |
list_tool_templates | List the tool templates you can create a tool from. | tools:read |
create_tool | Create an automation tool from a template. | tools:write |
update_tool | Update a tool's enabled state, name, description, or approval setting. | tools:write |
configure_tool_approval | Record how executions of a tool must be approved. | tools:write |
request_tool_credentials | Report whether a tool has all required configuration. | tools:write |
execute_tool | Run an automation tool with the arguments you pass. See the warning below. | tools:execute |
create_script | Create a script tool. It starts disabled with a skeleton code draft. | tools:write |
get_script_draft | Read a script tool's draft code, analysis, and diagnostics. | tools:read |
update_script_draft | Save a script tool's draft code. Risotto analyzes every save. | tools:write |
test_script | Run a script tool's draft code as a test execution. | tools:execute |
get_script_run | Read one script run's outcome and per-step trace. | tools:read |
get_last_script_test_run | Read the most recent test run for a script tool. | tools:read |
publish_script | Publish a script tool's draft as the live version. | tools:write |
list_credentials | List the credentials in the vault that you can use. Never the values. | tools:execute |
request_vault_credential | Ask for a new vault credential on a secure card. | tools:execute |
Custom API sources and templates (22 tools)
| Tool | What it does | Scope |
|---|---|---|
list_custom_api_sources | List the custom API sources (third-party REST integrations). | custom_api_sources:read |
get_custom_api_source | Inspect one source and its staged endpoint drafts. | custom_api_sources:read |
find_api_spec_candidates | Find a vendor's published API definition file on the web. | custom_api_sources:read |
list_custom_api_templates | List the vendor APIs Risotto ships a pinned specification for. | custom_api_sources:read |
get_custom_api_template | Inspect one template: its tag groups and endpoints. | custom_api_sources:read |
search_custom_api_endpoints | Search every shipped API specification for endpoints that match a description. | custom_api_sources:read |
record_excluded_capability_request | Record that you asked for an area that a template leaves out. | custom_api_sources:read |
create_custom_api_source | Create a custom API source. | custom_api_sources:write |
create_custom_api_source_from_template | Create a source from a template with all endpoints drafted. | custom_api_sources:write |
update_custom_api_source | Update a source's non-secret configuration. | custom_api_sources:write |
ingest_openapi_spec | Fetch an API definition by URL and stage every operation as a draft. | custom_api_sources:write |
ingest_openapi_spec_content | Stage every operation from a pasted API definition. | custom_api_sources:write |
ingest_attached_file | Stage operations from a file attached in the dashboard Assistant. | custom_api_sources:write |
ingest_confirmed_web_spec | Ground a source on a specification file found on the web. | custom_api_sources:write |
stage_custom_api_drafts | Stage hand-authored endpoint drafts on a source. | custom_api_sources:write |
import_curl_endpoint | Stage an endpoint draft parsed from a curl command. | custom_api_sources:write |
discard_custom_api_draft | Remove a staged endpoint draft. | custom_api_sources:write |
test_custom_api_draft | Run a staged draft against the real API before promotion. | custom_api_sources:write |
validate_custom_api_draft | Validate a staged read (GET) draft with one live test call. | custom_api_sources:write |
promote_custom_api_drafts | Promote staged read (GET) drafts into callable tools. | custom_api_sources:write |
construct_custom_api_write_tool | Turn a staged write draft into a disabled draft tool. | custom_api_sources:write |
request_custom_api_credentials | Report whether a source has its credentials. | custom_api_sources:write |
External MCP servers (8 tools)
| Tool | What it does | Scope |
|---|---|---|
list_external_mcp_servers | List the connected external MCP servers. | external_mcp_servers:read |
get_external_mcp_server | Inspect one server: its tool catalog, drift, and imported tools. | external_mcp_servers:read |
create_external_mcp_server | Connect a third-party MCP server and discover its tool catalog. | external_mcp_servers:write |
request_external_mcp_credentials | Report whether a server has its bearer token. | external_mcp_servers:write |
request_external_mcp_authorization | Report whether a server's OAuth 2.1 authorization is complete. | external_mcp_servers:write |
refresh_external_mcp_server | Fetch a server's remote tool catalog again. | external_mcp_servers:write |
import_external_mcp_tools | Import chosen remote tools as automation tools. | external_mcp_servers:write |
test_external_mcp_tool | Call a remote tool on the live server before you import it. | external_mcp_servers:write |
Access management (8 tools)
| Tool | What it does | Scope |
|---|---|---|
list_applications | List the applications that requestors can ask access to. | applications:read |
list_access_rules | List access rules with their state, application, limits, and approval. | access_rules:read |
get_access_rule | Get one access rule's full configuration. | access_rules:read |
get_access_rule_authoring_guide | Get the access-rule authoring guide as Markdown. | access_rules:write |
create_applications | Create up to 100 applications in one call. | access_rules:write |
update_application | Update an application's name, owner email, or keywords. | access_rules:write |
create_access_rules | Create up to 100 access rules in one call. New rules start disabled. | access_rules:write |
update_access_rule | Update one access rule. Omitted fields keep their value. | access_rules:write |
Organization settings, request sources, and identity provider (11 tools)
| Tool | What it does | Scope |
|---|---|---|
get_org_settings | Read agent instructions, approval timers, auto-resolve days, and the notifications channel. | settings:read |
update_org_setting | Set one organization setting. | settings:write |
find_slack_channels | Find Slack channels by name. Returns IDs for the channel tools. | settings:read |
set_slack_notifications_channel | Set the Slack channel where Risotto posts admin notifications. | settings:write |
list_request_sources | List every request source with its routing department and settings. | settings:read |
update_slack_channel_routing | Update how a Slack channel routes requests. | settings:write |
update_msteams_channel_routing | Update how a Microsoft Teams channel routes requests. | settings:write |
update_support_email_address | Update the settings of a support email address. | settings:write |
get_idp_configuration | Read how the identity provider is configured. | settings:read |
get_vendor_tenant_hosts | Read the vendor site that each connection stores, such as your Atlassian site. | settings:read |
request_okta_credentials | Report whether the Okta connection is configured. | settings:write |
Artifacts and audit log (8 tools)
| Tool | What it does | Scope |
|---|---|---|
list_artifacts | List the artifact pages (dynamic dashboards) with their URLs. | artifacts:read |
get_artifact | Get one artifact page, including its HTML. | artifacts:read |
list_artifact_tools | List the tools an artifact page can call. | artifacts:read |
create_artifact | Create an artifact page from a title, a complete HTML document, and the tools the page can call. | artifacts:write |
update_artifact | Change an artifact page. Omitted fields stay unchanged. A new html replaces the whole page. | artifacts:write |
delete_artifact | Delete an artifact page. Its audit log is kept. | artifacts:write |
list_audit_events | List configuration-change audit events. | audit:read |
get_audit_event | Get one audit event with its field-level diff. | audit:read |
Campaigns (2 tools)
| Tool | What it does | Scope |
|---|---|---|
list_campaigns | List campaigns, newest first, with type, state, send and due dates, and counts of total, completed, and awaiting recipients and failed deliveries. | campaigns:read |
list_campaign_responses | Get a campaign's message and form questions, and one page of recipients with their state, answers, and reactions. Filter by recipient state, for example to list who has not answered. Access review campaigns return an error. | campaigns:read |
Alerts (1 tool)
| Tool | What it does | Scope |
|---|---|---|
list_alerts | List the open error and warning alerts from the last 14 days, newest first, with each alert's full title and message. Read-only; it cannot dismiss an alert. | alerts:read |
The set of tools grows as Risotto adds capabilities. Call tools/list against your endpoint to see the current list of tools that your scopes allow, with input schemas.
Troubleshooting
401 Unauthorized
The bearer token is missing, malformed, expired, or revoked.
- The client should refresh its token automatically. If it doesn't, remove and re-add the MCP server in the client to trigger a fresh consent flow.
- If you configured the server with a Risotto API key instead of signing in, the response says so. Remove the key from the client's configuration and reconnect; the client prompts you to sign in with OAuth.
- The
WWW-Authenticateresponse header points to the OAuth discovery document — most clients use this automatically to recover. If you're building a custom client, follow that pointer.
403 insufficient_scope or access_denied
You are no longer in the organization, or none of the requested scopes is one that your role can hold.
- A user who is not in the organization gets
403withinsufficient_scope("Only org admins, managers, and members can use Risotto MCP."). - At consent, a Member whose client requests only scopes outside the Member scopes goes back to the client with
access_denied. - A
503withRetry-After: 30means that Risotto could not read your role. Try again.
Consent screen redirects fail or loops
Risotto's Dynamic Client Registration follows RFC 8252 for native/desktop clients: they register either a localhost loopback redirect URI or a private-use URI scheme (like cursor://). Claude Desktop and the MCP Inspector use loopback; Cursor uses its cursor:// scheme, and a single registration can mix native and web redirect URIs.
Hosted clients like ChatGPT are different — they register their own public HTTPS redirect URI, which Risotto's DCR accepts. If you're building a custom desktop client, use a loopback or private-use-scheme redirect. If you're building a custom hosted/web client and registration is failing, double-check the redirect URI is a valid HTTPS URL your service controls.
Tool call returns a missing scope error
Scope failures come back as a successful JSON-RPC response whose result.isError is true, with a message naming the missing scope (for example, tickets:read).
Revoke the client in the dashboard and reconnect — the consent screen lets you approve the additional scope. A Member cannot approve a scope outside the Member scopes. Ask an Org Admin for the Admin or Manager role.
429 Too Many Requests
You've hit Risotto's rate limit. /mcp requests are throttled per credential at 1,000 requests per hour by default, and OAuth token issuance is throttled per client.
The response includes Retry-After and X-RateLimit-* headers showing the reset window. Back off until the window resets, or contact support if you consistently need higher limits.
Tools don't appear in the client
- Restart the client after editing its config file — most clients only read MCP config at startup.
- Run the
curlsnippet above to confirm the endpoint is reachable. tools/listreturns only the tools that the credential's scopes allow. If a tool you expect is missing, check the scopes you granted, and for OAuth, check your organization role. See Scopes and organization roles.
Something wrong or missing? Report an issue · View as Markdown