Risotto MCP Server

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 116 tools. You can work with tickets, knowledge, users, departments, runbooks, automation tools, access rules, and organization settings. See Available tools for the full list. Two authentication methods are supported:

OAuth 2.1 (recommended) — interactive clients run a standard browser-based authorization flow. Each user signs in with their own Risotto identity, so tool calls are attributed and audited per-person. This is the right choice for Claude Desktop, Cursor, the MCP Inspector, and any client that ships a built-in OAuth UI.
API key — a long-lived rso_live_… key sent as a request header. Suited to headless scripts, CI, and other callers that can’t drive a browser-based consent flow.

OAuth clients self-register with Risotto the first time they connect — there is no “create OAuth client” step in the dashboard. You only need the server URL.

Prerequisites

A Risotto account.
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 → Integrations → MCP in the dashboard. Both authentication methods below use the same URL.

Connect with OAuth (recommended)

Add the MCP server to your client

Most MCP clients only need the server URL — they handle registration and the consent flow automatically.

Claude Desktop
Cursor
ChatGPT
MCP Inspector

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.

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.

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.

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. The same scope vocabulary applies to API keys. A scope grants the tools listed under it in Available tools.

Scope	Grants
`tickets:read`	List and read tickets, comments, ticket insights, and automation opportunities
`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 and read department and Tier 2 Assistant settings
`departments:write`	Create departments and change department and Tier 2 Assistant settings
`runbooks:read`	Read runbooks, drafts, revisions, runbook templates, and forms
`runbooks:write`	Create, update, duplicate, and delete runbooks and forms
`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
`access_rules:read`	List applications and access rules
`access_rules:write`	Create and update applications and access rules
`settings:read`	Read organization settings, request sources, ticket fields, 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`	Delete artifact pages
`audit:read`	Read the configuration audit log
`triggers:read`	Reserved. No MCP tool uses this scope yet
`triggers:write`	Reserved. No MCP tool uses this scope yet

Follow least privilege. For a read-only assistant, approve tickets:read, knowledge:read, users:read, departments:read, runbooks:read, and tools:read. Add write or execute scopes only when a workflow needs them.

Ticket access via MCP respects the authenticated user’s department membership and role, the same as the dashboard and chat — a tickets:read scope doesn’t grant visibility into tickets outside the departments that user belongs to.

Manage authorized clients

From Settings → Integrations → MCP 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.

Connect with an API key

API keys are the right choice when the caller can’t run a browser — for example, a CI job or a server-side automation.

Issue a key

In the dashboard, go to Settings → Integrations → Credential Vault. In the Risotto API Keys section, click Create Key.Give it a recognizable name like Onboarding bot — production so you can revoke a single caller’s access later.

Select scopes

Grant only the scopes the caller needs. See the scope reference above.

Copy the key

The key starts with rso_live_. Copy it immediately — you will not be able to see it again. If you lose it, revoke it and issue a new one.

Send the key in an Authorization: Bearer header to the same MCP server URL from your dashboard. The MCP endpoint does not accept the X-API-Key header that the REST API accepts.

curl -sS YOUR_MCP_SERVER_URL \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer rso_live_YOUR_KEY_HERE" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

This returns every tool the server registers, with its input schema. The list is the same for every credential. Risotto checks the scope when you call a tool, not when you list tools.

Available tools

The server registers 116 tools. Each tool needs one scope. tools/list returns every tool. A call to a tool outside the credential’s 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.

Tickets and comments (8 tools)

Tool	What it does	Scope
`list_tickets`	List and filter 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.	`tickets:read`
`list_ticket_custom_fields`	List the additional ticket fields defined for the organization.	`settings:read`
`create_ticket_custom_field`	Create an additional ticket field in a department.	`settings:write`

Knowledge (3 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`

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 (10 tools)

Tool	What it does	Scope
`list_departments`	List departments with descriptions, ticket prefixes, and member counts.	`departments:read`
`get_department`	Read every setting of one department.	`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`
`get_tier_2_assistant_config`	Read whether the Tier 2 Assistant starts automatically for a department.	`departments:read`
`update_tier_2_assistant_config`	Turn the Tier 2 Assistant auto start on or off for a department.	`departments: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:read`
`list_runbook_revisions`	List every version of a runbook, newest first.	`runbooks:read`
`get_runbook_authoring_guide`	Get the runbook authoring guide as Markdown.	`runbooks:read`
`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:read`
`get_runbook_template`	Get a runbook template with its content.	`runbooks:read`
`list_forms`	List the structured-input forms, newest first.	`runbooks:read`
`get_form`	Get a form’s fields and the runbooks that reference it.	`runbooks:read`
`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 (15 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`
`test_tool`	Run a tool against its live configuration and report the outcome.	`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`

Custom API sources and templates (21 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`
`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.	`access_rules: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 (10 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`
`request_okta_credentials`	Report whether the Okta connection is configured.	`settings:write`

Artifacts and audit log (6 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`
`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`

Grant tools:execute only to a key whose holder may approve every tool it can reach. execute_tool runs the tool at once, also when the tool’s approval setting is Required in the dashboard. execute_tool needs an API key credential. A call from an OAuth client fails.

Five tools collect secrets on a secure card in the dashboard Assistant: request_tool_credentials, request_custom_api_credentials, request_external_mcp_credentials, request_external_mcp_authorization, and request_okta_credentials. From an external MCP client they only report the current state. Enter the secret in the dashboard instead. ingest_attached_file reads a file uploaded in the dashboard Assistant and has no use from an external client.

The set of tools grows as Risotto adds capabilities. Call tools/list against your endpoint to see the current list with input schemas.

Troubleshooting

401 Unauthorized

The bearer token or API key is missing, malformed, expired, or revoked.

OAuth: 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.
API key: confirm the value starts with rso_live_ and was copied in full, and that the key hasn’t been revoked in the dashboard.
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.

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

OAuth: revoke the client in the dashboard and reconnect — the consent screen lets you approve the additional scope.
API key: add the scope on the key in the dashboard, or issue a new key with the correct scopes.

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 every tool, whatever the credential’s scopes. If a tool call fails instead, check the scope error above.

​Risotto MCP Server

​Prerequisites

​Find your MCP server URL

​Connect with OAuth (recommended)

​Available scopes

​Manage authorized clients

​Connect with an API key

​Available tools

​Troubleshooting

Risotto MCP Server

Prerequisites

Find your MCP server URL

Connect with OAuth (recommended)

Available scopes

Manage authorized clients

Connect with an API key

Available tools

Troubleshooting