Docs

Developers / MCP server

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

  1. 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_URL with 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_URL

    The Inspector opens a browser tab for consent, then exposes a JSON-RPC console for poking at the server directly.

  2. 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.

  3. 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.

ScopeGrants
tickets:readList and read tickets, comments, ticket insights, and ticket field definitions
tickets:writeCreate, update, resolve, and escalate tickets, and add comments
tickets:deleteReserved. No MCP tool uses this scope yet
knowledge:readSearch indexed knowledge, list knowledge sources, check a document's index
users:readFind users and read their profiles and groups
departments:readList departments (ID and name only without config:read)
departments:writeCreate departments and change department settings
runbooks:readRead runbooks and a ticket's runbook history
runbooks:writeCreate, update, duplicate, and delete runbooks and forms, and read drafts, revisions, templates, forms, and the authoring guide
tools:readList automation tools and tool templates, read script drafts and runs
tools:writeCreate and update automation tools and script tools, set tool approval
tools:executeRun and test automation tools and scripts
custom_api_sources:readList custom API sources and browse the shipped API templates
custom_api_sources:writeCreate custom API sources and stage, test, and promote endpoint drafts
external_mcp_servers:readList connected external MCP servers
external_mcp_servers:writeConnect external MCP servers and import their tools
applications:readList the applications that requestors can ask access to
access_rules:readList access rules
access_rules:writeCreate and update applications and access rules
settings:readRead organization settings, request sources, and the IdP config
settings:writeUpdate organization settings, request routing, ticket fields, and Okta config
artifacts:readList and read artifact pages
artifacts:writeCreate, update, and delete artifact pages
audit:readRead the configuration audit log
campaigns:readList campaigns and read their recipients and submitted responses
alerts:readList the open error and warning alerts from the last 14 days, the same alerts as the Alerts page
categories:readList the ticket categories of a department
categories:writeCreate and update the ticket categories of a department, and read the category authoring guide
config:readRead Assistant settings, full department settings, and the automation opportunities report
config:writeUpdate Assistant settings
triggers:readReserved. No MCP tool uses this scope yet
triggers:writeReserved. 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, and tools:execute. A Member can run and test only the tools of the departments that they supervise. A Member cannot hold categories: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_ticket for another requestor ("You can create tickets only for yourself"), an add_comment as another author ("You can comment only as yourself"), and a search_knowledge or check_document_index_status on behalf of another user ("You can search only with your own access").
  • search_knowledge with a dept_id works only for a department where the Member can read tickets. Without dept_id, it searches only documents shared with the whole organization.
  • list_runbooks and get_runbook return 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)
ToolWhat it doesScope
list_ticketsList, filter, and search tickets. Returns up to 100 tickets per page.tickets:read
get_ticketGet one ticket with its comments and workflow state.tickets:read
list_ticket_commentsList the comments on a ticket.tickets:read
create_ticketCreate a ticket. The agent processes it like a ticket from chat.tickets:write
update_ticketUpdate ticket fields. Only the fields you pass change.tickets:write
add_commentAdd a comment to a ticket.tickets:write
resolve_ticketMark a ticket as resolved. Also resolves the synced external ticket.tickets:write
escalate_ticketEscalate a ticket to human support. Sends a Slack notification and stops the agent.tickets:write
Ticket insights (7 tools)
ToolWhat it doesScope
get_ticket_runbook_match_historyShow which runbooks matched a ticket and why.tickets:read
get_ticket_retrieval_historyShow the knowledge that Risotto retrieved for a ticket.tickets:read
get_ticket_agent_activityShow the agent's steps on a ticket in order.tickets:read
list_ticket_runbook_historyList the runbooks matched to a ticket and whether the agent followed them.runbooks:read
get_automation_opportunitiesReport the requests Risotto could still automate, ranked by ticket volume. Also needs tickets:read.config:read
list_ticket_custom_fieldsList the additional ticket fields defined for the organization.tickets:read
create_ticket_custom_fieldCreate an additional ticket field in a department.settings:write
Knowledge (4 tools)
ToolWhat it doesScope
search_knowledgeSearch indexed knowledge with semantic and keyword retrieval.knowledge:read
list_knowledge_sourcesList the connected knowledge sources and their index IDs.knowledge:read
check_document_index_statusCheck whether a document is in the index, by URL or title.knowledge:read
get_knowledge_gap_reportRead 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)
ToolWhat it doesScope
find_usersSearch users by name or email.users:read
get_user_profileGet a user's profile from the identity provider.users:read
get_user_groupsGet the identity provider groups a user belongs to.users:read
Departments and Tier 2 Assistant (14 tools)
ToolWhat it doesScope
list_departmentsList departments with descriptions, ticket prefixes, and member counts. Without config:read, returns only the ID and name.departments:read
get_departmentRead every setting of one department. Without config:read, returns only the ID and name.departments:read
create_departmentCreate a department from a name and a description.departments:write
update_department_settingSet one department setting, such as the name or description.departments:write
update_department_ticket_sync_settingSet one Ticket Sync toggle for the department's external ticketing system.departments:write
set_department_ticket_prefixSet the ticket prefix, for example IT in IT-123.departments:write
set_department_agent_channelSet the Slack channel where Risotto posts escalations for the department.departments:write
set_department_escalation_contactSet the person Risotto notifies when a ticket escalates.departments:write
list_department_categoriesList a department's ticket categories, including inactive ones. A sub-department returns its parent's categories.categories:read
create_department_categoryAdd 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_categoryChange 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_guideGet the guidelines for writing and changing categories, as Markdown.categories:write
get_tier_2_assistant_configRead a department's Assistant settings: auto start and the investigation and execution instructions.config:read
update_tier_2_assistant_configSet a department's Assistant auto start, investigation instructions, or execution instructions. Omitted settings stay unchanged.config:write
Runbooks, templates, and forms (17 tools)
ToolWhat it doesScope
list_runbooksList and filter runbooks.runbooks:read
get_runbookGet a runbook's current version: conditions, instructions, and tool references.runbooks:read
get_runbook_draftGet a runbook's pending draft revision.runbooks:write
list_runbook_revisionsList every version of a runbook, newest first.runbooks:write
get_runbook_authoring_guideGet the runbook authoring guide as Markdown.runbooks:write
create_runbookCreate a runbook. It is active and indexed immediately.runbooks:write
update_runbookUpdate one or more fields on a runbook.runbooks:write
upsert_runbook_draftStage or replace a pending draft revision on a runbook.runbooks:write
duplicate_runbookCopy a runbook. The copy starts disabled with " (Copy)" in its title.runbooks:write
delete_runbookSoft-delete a runbook. The version history is kept.runbooks:write
list_runbook_templatesList the curated runbook templates and whether your tools are ready for them.runbooks:write
get_runbook_templateGet a runbook template with its content.runbooks:write
list_formsList the structured-input forms, newest first.runbooks:write
get_formGet a form's fields and the runbooks that reference it.runbooks:write
create_formCreate a form for runbooks to collect answers from requestors.runbooks:write
update_formUpdate a form. Omitted arguments stay unchanged.runbooks:write
delete_formDelete a form.runbooks:write
Automation tools and scripts (16 tools)
ToolWhat it doesScope
list_toolsList the organization's automation tools with their parameter schemas.tools:read
list_tool_templatesList the tool templates you can create a tool from.tools:read
create_toolCreate an automation tool from a template.tools:write
update_toolUpdate a tool's enabled state, name, description, or approval setting.tools:write
configure_tool_approvalRecord how executions of a tool must be approved.tools:write
request_tool_credentialsReport whether a tool has all required configuration.tools:write
execute_toolRun an automation tool with the arguments you pass. See the warning below.tools:execute
create_scriptCreate a script tool. It starts disabled with a skeleton code draft.tools:write
get_script_draftRead a script tool's draft code, analysis, and diagnostics.tools:read
update_script_draftSave a script tool's draft code. Risotto analyzes every save.tools:write
test_scriptRun a script tool's draft code as a test execution.tools:execute
get_script_runRead one script run's outcome and per-step trace.tools:read
get_last_script_test_runRead the most recent test run for a script tool.tools:read
publish_scriptPublish a script tool's draft as the live version.tools:write
list_credentialsList the credentials in the vault that you can use. Never the values.tools:execute
request_vault_credentialAsk for a new vault credential on a secure card.tools:execute
Custom API sources and templates (22 tools)
ToolWhat it doesScope
list_custom_api_sourcesList the custom API sources (third-party REST integrations).custom_api_sources:read
get_custom_api_sourceInspect one source and its staged endpoint drafts.custom_api_sources:read
find_api_spec_candidatesFind a vendor's published API definition file on the web.custom_api_sources:read
list_custom_api_templatesList the vendor APIs Risotto ships a pinned specification for.custom_api_sources:read
get_custom_api_templateInspect one template: its tag groups and endpoints.custom_api_sources:read
search_custom_api_endpointsSearch every shipped API specification for endpoints that match a description.custom_api_sources:read
record_excluded_capability_requestRecord that you asked for an area that a template leaves out.custom_api_sources:read
create_custom_api_sourceCreate a custom API source.custom_api_sources:write
create_custom_api_source_from_templateCreate a source from a template with all endpoints drafted.custom_api_sources:write
update_custom_api_sourceUpdate a source's non-secret configuration.custom_api_sources:write
ingest_openapi_specFetch an API definition by URL and stage every operation as a draft.custom_api_sources:write
ingest_openapi_spec_contentStage every operation from a pasted API definition.custom_api_sources:write
ingest_attached_fileStage operations from a file attached in the dashboard Assistant.custom_api_sources:write
ingest_confirmed_web_specGround a source on a specification file found on the web.custom_api_sources:write
stage_custom_api_draftsStage hand-authored endpoint drafts on a source.custom_api_sources:write
import_curl_endpointStage an endpoint draft parsed from a curl command.custom_api_sources:write
discard_custom_api_draftRemove a staged endpoint draft.custom_api_sources:write
test_custom_api_draftRun a staged draft against the real API before promotion.custom_api_sources:write
validate_custom_api_draftValidate a staged read (GET) draft with one live test call.custom_api_sources:write
promote_custom_api_draftsPromote staged read (GET) drafts into callable tools.custom_api_sources:write
construct_custom_api_write_toolTurn a staged write draft into a disabled draft tool.custom_api_sources:write
request_custom_api_credentialsReport whether a source has its credentials.custom_api_sources:write
External MCP servers (8 tools)
ToolWhat it doesScope
list_external_mcp_serversList the connected external MCP servers.external_mcp_servers:read
get_external_mcp_serverInspect one server: its tool catalog, drift, and imported tools.external_mcp_servers:read
create_external_mcp_serverConnect a third-party MCP server and discover its tool catalog.external_mcp_servers:write
request_external_mcp_credentialsReport whether a server has its bearer token.external_mcp_servers:write
request_external_mcp_authorizationReport whether a server's OAuth 2.1 authorization is complete.external_mcp_servers:write
refresh_external_mcp_serverFetch a server's remote tool catalog again.external_mcp_servers:write
import_external_mcp_toolsImport chosen remote tools as automation tools.external_mcp_servers:write
test_external_mcp_toolCall a remote tool on the live server before you import it.external_mcp_servers:write
Access management (8 tools)
ToolWhat it doesScope
list_applicationsList the applications that requestors can ask access to.applications:read
list_access_rulesList access rules with their state, application, limits, and approval.access_rules:read
get_access_ruleGet one access rule's full configuration.access_rules:read
get_access_rule_authoring_guideGet the access-rule authoring guide as Markdown.access_rules:write
create_applicationsCreate up to 100 applications in one call.access_rules:write
update_applicationUpdate an application's name, owner email, or keywords.access_rules:write
create_access_rulesCreate up to 100 access rules in one call. New rules start disabled.access_rules:write
update_access_ruleUpdate one access rule. Omitted fields keep their value.access_rules:write
Organization settings, request sources, and identity provider (11 tools)
ToolWhat it doesScope
get_org_settingsRead agent instructions, approval timers, auto-resolve days, and the notifications channel.settings:read
update_org_settingSet one organization setting.settings:write
find_slack_channelsFind Slack channels by name. Returns IDs for the channel tools.settings:read
set_slack_notifications_channelSet the Slack channel where Risotto posts admin notifications.settings:write
list_request_sourcesList every request source with its routing department and settings.settings:read
update_slack_channel_routingUpdate how a Slack channel routes requests.settings:write
update_msteams_channel_routingUpdate how a Microsoft Teams channel routes requests.settings:write
update_support_email_addressUpdate the settings of a support email address.settings:write
get_idp_configurationRead how the identity provider is configured.settings:read
get_vendor_tenant_hostsRead the vendor site that each connection stores, such as your Atlassian site.settings:read
request_okta_credentialsReport whether the Okta connection is configured.settings:write
Artifacts and audit log (8 tools)
ToolWhat it doesScope
list_artifactsList the artifact pages (dynamic dashboards) with their URLs.artifacts:read
get_artifactGet one artifact page, including its HTML.artifacts:read
list_artifact_toolsList the tools an artifact page can call.artifacts:read
create_artifactCreate an artifact page from a title, a complete HTML document, and the tools the page can call.artifacts:write
update_artifactChange an artifact page. Omitted fields stay unchanged. A new html replaces the whole page.artifacts:write
delete_artifactDelete an artifact page. Its audit log is kept.artifacts:write
list_audit_eventsList configuration-change audit events.audit:read
get_audit_eventGet one audit event with its field-level diff.audit:read
Campaigns (2 tools)
ToolWhat it doesScope
list_campaignsList 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_responsesGet 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)
ToolWhat it doesScope
list_alertsList 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-Authenticate response 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 403 with insufficient_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 503 with Retry-After: 30 means that Risotto could not read your role. Try again.
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 curl snippet above to confirm the endpoint is reachable.
  • tools/list returns 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