Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tryrisotto.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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. You can look up tickets, search indexed knowledge, find users and departments, and trigger runbook tools. 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.
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.
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, review the scopes the client is requesting, and click Allow.The scopes you approve at this screen bound that specific client’s access — they don’t change your overall account permissions.
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. The same scope vocabulary applies to API keys.
ScopeGrants
tickets:readListing and reading tickets and their comments
tickets:writeCreating, updating, resolving, escalating tickets and adding comments
knowledge:readSearching indexed knowledge
users:readLooking up users and user profiles
departments:readListing departments
tools:readListing runbook tools
tools:executeExecuting runbook tools that are not approval-gated
Follow least-privilege. For a read-only assistant, approving tickets:read, knowledge:read, users:read, departments:read, and tools:read is a reasonable starting point — add write or execute scopes only when needed.

​
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.
1

Issue a key

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

Select scopes

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

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 as an Authorization: Bearer header (or the equivalent X-API-Key header) to the same MCP server URL from your dashboard: 
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 the authoritative list of tools available to that key.

​
Available capabilities

The MCP server exposes Risotto capabilities in these areas:
  • Tickets — list, read, create, update, comment on, resolve, and escalate tickets
  • Knowledge — search your indexed knowledge base
  • Users & departments — find users, look up profiles, list departments
  • Runbook tools — list available runbook tools and execute non-approval-gated ones
The specific tools available are governed by the scopes on the credential making the call. The set of tools evolves as we add capabilities — to see the authoritative current list, call tools/list against the endpoint.

​
Troubleshooting

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.
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.
You’ve hit Risotto’s rate limit. /mcp requests are throttled per credential, 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.
  • 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.
  • If tools/list returns an empty list, the credential has no scopes granted. For API keys, add at least tools:read plus whichever resource scopes you want to use. For OAuth, revoke the client and reconnect to approve scopes.