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

# MCP Server

> Connect Claude Desktop, Cursor, and other MCP clients to Risotto to query tickets, search knowledge, and execute runbook tools.

# Risotto MCP Server

Risotto exposes a [Model Context Protocol](https://modelcontextprotocol.io) 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.

<Info>
  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.
</Info>

## 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:

```text theme={null}
https://api.tryrisotto.com/o/<org_id>/mcp
```

Copy your organization's specific URL from [**Settings → Integrations → MCP**](https://dashboard.tryrisotto.com/settings/integrations/mcp) in the dashboard. Both authentication methods below use the same URL.

## Connect with OAuth (recommended)

<Steps>
  <Step title="Add the MCP server to your client">
    Most MCP clients only need the server URL — they handle registration and the consent flow automatically.

    <Tabs>
      <Tab title="Claude Desktop">
        Edit your Claude Desktop config file:

        * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
        * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

        ```json theme={null}
        {
          "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.
      </Tab>

      <Tab title="Cursor">
        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.
      </Tab>

      <Tab title="ChatGPT">
        ChatGPT connects to Risotto as a custom MCP connector.

        <Note>
          Custom connectors require a ChatGPT **Pro, Team, or Enterprise** plan with **developer mode** enabled.
        </Note>

        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.
      </Tab>

      <Tab title="MCP Inspector">
        ```bash theme={null}
        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.
      </Tab>
    </Tabs>
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

### Available scopes

OAuth clients request scopes at consent time. The same scope vocabulary applies to API keys.

| Scope              | Grants                                                                |
| ------------------ | --------------------------------------------------------------------- |
| `tickets:read`     | Listing and reading tickets and their comments                        |
| `tickets:write`    | Creating, updating, resolving, escalating tickets and adding comments |
| `knowledge:read`   | Searching indexed knowledge                                           |
| `users:read`       | Looking up users and user profiles                                    |
| `departments:read` | Listing departments                                                   |
| `tools:read`       | Listing runbook tools                                                 |
| `tools:execute`    | Executing runbook tools that are not approval-gated                   |

<Tip>
  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.
</Tip>

<Note>
  Ticket access via MCP respects the authenticated user's department membership and role, the same as the dashboard and Slack — a `tickets:read` scope doesn't grant visibility into tickets outside the departments that user belongs to.
</Note>

### Manage authorized clients

From [**Settings → Integrations → MCP**](https://dashboard.tryrisotto.com/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.

<Steps>
  <Step title="Issue a key">
    In the dashboard, go to [**Settings → Integrations → API Keys**](https://dashboard.tryrisotto.com/settings/integrations/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.
  </Step>

  <Step title="Select scopes">
    Grant only the scopes the caller needs. See the [scope reference](#available-scopes) above.
  </Step>

  <Step title="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.
  </Step>
</Steps>

Send the key as an `Authorization: Bearer` header (or the equivalent `X-API-Key` header) to the same MCP server URL from your dashboard:

```bash theme={null}
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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Consent screen redirects fail or loops">
    Risotto's Dynamic Client Registration follows [RFC 8252](https://datatracker.ietf.org/doc/html/rfc8252#section-7.3) 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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="429 Too Many Requests">
    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.
  </Accordion>

  <Accordion title="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.
    * 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.
  </Accordion>
</AccordionGroup>