diff --git a/docs/extensibility/model-context-protocol/available-tools.mdx b/docs/extensibility/model-context-protocol/available-tools.mdx index 2903c46b9101a..c20fab11631b7 100644 --- a/docs/extensibility/model-context-protocol/available-tools.mdx +++ b/docs/extensibility/model-context-protocol/available-tools.mdx @@ -6,14 +6,23 @@ sidebar_label: Available Tools sidebar_position: 3 sidebar_class_name: mcp keywords: ['mcp'] -description: SailPoint's MCP Server Tools +description: Tools provided by SailPoint's MCP servers slug: /extensibility/mcp-available-tools tags: ['MCP'] --- -The SailPoint MCP Server provides integration with SailPoint's Request Center, enabling automated access management through four core tools. +SailPoint provides more than one MCP server. Each server has its own URL and its own set of tools. To connect to a server, refer to [Getting Started](./getting-started.mdx). -## Overview +| Server | Global URL | Tools | +|---|---|---| +| [Access Requests](#access-requests-server) | `https://mcp.sailpoint.com/latest/access-requests/mcp` | [list-requestable](#list-requestable)
[create-access-request](#create-access-request)
[view-access-requests](#view-access-requests)
[cancel-access-request](#cancel-access-request) | +| [Identity Intelligence](#identity-intelligence-server) | `https://mcp.sailpoint.com/latest/intelligence/mcp` | [get-identity-intelligence](#get-identity-intelligence)
[get-identity-resource](#get-identity-resource) | + +--- + +## Access Requests Server + +The Access Requests server provides integration with SailPoint's Request Center, enabling automated access management through four core tools. This server supports the following operations: - Search for requestable access items @@ -21,10 +30,6 @@ This server supports the following operations: - View access request status - Cancel pending access requests ---- - -## Tools - ### list-requestable Search for requestable objects (roles, entitlements, access profiles) in the SailPoint Request Center and list the available accounts for each. @@ -195,9 +200,9 @@ The system automatically adds "Canceled by AI on behalf of the user adam.archer" --- -## Error Handling +### Error Handling -All tools return a consistent error structure when operations fail: +All Access Requests tools return a consistent error structure when operations fail: ```json { @@ -210,4 +215,61 @@ Common error scenarios include: - Invalid or missing required parameters - Access denied to requested resources - Network connectivity issues -- Misconfigured requestable objects \ No newline at end of file +- Misconfigured requestable objects + +--- + +## Identity Intelligence Server + +The Identity Intelligence server provides two read-only tools that AI clients can use to investigate human identities in Identity Security Cloud (ISC). The tools do not change data in your tenant. + +This server supports the following operations: +- Get the full intelligence package for one identity: profile, access, risk, and access history +- Get one paginated sub-resource for an identity: accounts, rare access, access items, or certifications + +:::note Human identities only +The Identity Intelligence server currently supports only human identities. +::: + +:::info Required access +The token or OAuth session that you use must have the `sp:identity-sec-intel:read` scope. This is the least permissive scope for this server. `sp:scopes:all` also works. It must also carry a user identity, so use an OAuth session or a personal access token (PAT). Your tenant must also have the MCP Server and Response and Remediation licenses. +::: + +### get-identity-intelligence + +Retrieve the full intelligence package for one human identity. The package includes the identity's profile, access, risk, and access history. + +#### Parameters + +Pass exactly one of `id` or `email`. + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `id` | string | Conditional | ID of the human identity | +| `email` | string | Conditional | Email address of the human identity | + +:::warning Plain values only +Pass `id` and `email` as plain strings, for example `2c9180835d2e5168015d32f890ca1581` or `adam.archer@example.com`. Do not use list-filter syntax such as `id eq ""` or `email eq ""`. +::: + +--- + +### get-identity-resource + +Retrieve one paginated sub-resource for a human identity. Use this tool when you need more detail than [get-identity-intelligence](#get-identity-intelligence) returns, or when you need to page through a long list. + +#### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `resource` | string | Yes | Sub-resource to retrieve: `accounts`, `rare-access`, `access-items`, or `certifications` | +| `identityId` | string | Conditional | ID of the human identity. Use on the first page only. | +| `email` | string | Conditional | Email address of the human identity. Use on the first page only. | +| `nextUrl` | string | Conditional | HAL continuation link from the previous page's response. Use to get the next page. | +| `limit` | integer | No | Page size, from 1 to 100 | + +#### Pagination + +1. For the first page, pass `resource` and either `identityId` or `email`. +2. If the response contains a continuation link, pass that link as `nextUrl` to get the next page. +3. Repeat step 2 until the response does not contain a continuation link. \ No newline at end of file diff --git a/docs/extensibility/model-context-protocol/getting-started.mdx b/docs/extensibility/model-context-protocol/getting-started.mdx index cdfdae46cf565..98d0116a42225 100644 --- a/docs/extensibility/model-context-protocol/getting-started.mdx +++ b/docs/extensibility/model-context-protocol/getting-started.mdx @@ -13,122 +13,226 @@ tags: ['MCP'] ## Overview -The SailPoint MCP (Model Context Protocol) Server enables AI applications to interact with SailPoint's identity governance platform through a standardized interface. This guide walks you through setting up your first connection and testing the available tools. +The SailPoint MCP (Model Context Protocol) Server enables AI applications to interact with SailPoint's identity governance platform through a standardized interface. This guide shows you how to connect to the SailPoint MCP servers with the MCP Inspector and test the available tools. + +SailPoint provides more than one MCP server. Each server has its own URL and its own set of tools: + +| Server | Global URL | Purpose | +|---|---|---| +| Access Requests | `https://mcp.sailpoint.com/latest/access-requests/mcp` | Search for requestable items, and create, view, and cancel access requests. | +| Identity Intelligence | `https://mcp.sailpoint.com/latest/intelligence/mcp` | Investigate human identities: profile, access, risk, access history, and certifications. Read-only. | + +The global URLs work for all tenants without any tenant-specific configuration. They are the recommended entry point for AI client integration. **What you'll accomplish:** -- [Connect to the SailPoint MCP server using the MCP Inspector](#step-2-configure-the-connection) -- [Authenticate with your SailPoint tenant](#step-3-set-up-authentication) -- [List and explore available tools](#list-available-tools) +- [Create an API client in ISC](#step-1-create-an-api-client-in-isc) +- [Prepare the SailPoint config file](#step-2-prepare-the-sailpoint-config-file) +- [Launch the MCP Inspector with the SailPoint servers](#step-3-launch-the-mcp-inspector) +- [Connect and authenticate with your SailPoint tenant](#step-4-connect-to-a-server) +- [List and explore available tools](#step-5-list-available-tools) ## Prerequisites -Before you begin, ensure you have: +Before you begin, make sure that you have: -- **Access to a SailPoint tenant** with API access enabled -- **Valid authentication credentials** - refer to our [Authentication documentation](../../api/authentication.md) for details -- **Internet connection** for accessing the web-based MCP Inspector +- **Access to a SailPoint tenant** with API access enabled, and permission to create API clients +- **Node.js** installed, so that you can run `npx` - **Modern web browser** (Chrome, Firefox, Safari, or Edge) -## Step 1: Launch the MCP Inspector - -The MCP Inspector is a web-based tool that makes it easy to connect to and test MCP servers without writing code. +## Step 1: Create an API Client in ISC -Run the following command in your terminal: - -```bash -npx @modelcontextprotocol/inspector@latest -``` +The MCP Inspector uses OAuth to sign you in to your tenant. SailPoint's authorization server does not support Dynamic Client Registration, so you must create an API client in ISC and give its Client ID to the Inspector. -**What happens next:** -- If this is your first time running the command, npm will ask to install the package - enter `y` to confirm -- Your default web browser will automatically open the MCP Inspector interface +In ISC, go to **Admin > Security Settings > API Management** and create a new API client: -![MCP Inspector](./img/mcp-inspector.png) +1. Set the client type to **Public**. +2. Enable the **Authorization Code** and **Refresh Token** grant types. +3. Set the **Redirect URL** to `http://localhost:6274/oauth/callback` (the MCP Inspector's OAuth callback). +4. Set the **Scope** to the scopes of the servers that you want to use. If you use both servers with one Client ID, add both scopes. -## Step 2: Configure the Connection +Save the client and copy the **Client ID**. -### Set the Transport Type +Each server requires a different scope: -In the MCP Inspector sidebar, locate the **Transport Type** dropdown menu and select `Streamable HTTP`. +| Server | Scope | +|---|---| +| Access Requests | `sp:scopes:all` | +| Identity Intelligence | `sp:identity-sec-intel:read` | + +## Step 2: Prepare the SailPoint Config File + +1. Download the ready-made Inspector config: [sailpoint-mcp-inspector.json](pathname:///files/sailpoint-mcp-inspector.json). It contains: + + ```json + { + "mcpServers": { + "sailpoint-access-requests": { + "type": "streamable-http", + "url": "https://mcp.sailpoint.com/latest/access-requests/mcp", + "oauth": { + "clientId": "YOUR_CLIENT_ID", + "scopes": "sp:scopes:all" + } + }, + "sailpoint-identity-intelligence": { + "type": "streamable-http", + "url": "https://mcp.sailpoint.com/latest/intelligence/mcp", + "oauth": { + "clientId": "YOUR_CLIENT_ID", + "scopes": "sp:identity-sec-intel:read" + } + } + } + } + ``` + +2. Open the file and replace each `YOUR_CLIENT_ID` with the Client ID from [Step 1](#step-1-create-an-api-client-in-isc). You can use the same Client ID for every server. + +The `oauth` block fills in the OAuth settings for each server, so you do not need to enter them in the Inspector: + +- `clientId`: the Client ID of your ISC API client. +- `scopes`: the OAuth scopes to request for that server. The file already contains the scope of each server, as listed in [Step 1](#step-1-create-an-api-client-in-isc). Enter scopes as one string, separated by spaces, not as an array. If a field has the wrong type, the Inspector ignores the whole `oauth` block. + +Do not add a `clientSecret`. The ISC API client is a public client that uses PKCE. + +:::tip Only need one server? +Delete the servers you don't need from `sailpoint-mcp-inspector.json`. +::: -### Enter Your Server URL +## Step 3: Launch the MCP Inspector -SailPoint provides two MCP URL options: +The MCP Inspector is a web-based tool that you can use to connect to and test MCP servers without writing code. -**Global URL (recommended):** +In the folder that contains `sailpoint-mcp-inspector.json`, run this command: -``` -https://mcp.sailpoint.com/latest/access-requests/mcp +```bash +npx @modelcontextprotocol/inspector@latest --catalog sailpoint-mcp-inspector.json ``` -This URL works for all tenants without any tenant-specific configuration. It is the recommended entry point for AI client integration. +If this is your first time running the command, npm asks to install the package. Enter `y` to confirm. Your default web browser then opens the MCP Inspector. -**Tenant-specific URL:** +The Inspector opens on the **Servers** page. The page shows a card for each server in the file: `sailpoint-access-requests` and `sailpoint-identity-intelligence`. Each card shows the transport (**Streamable HTTP**), the server URL, and these actions: -``` -https://[tenant].api.identitynow.com/latest/access-requests/mcp -``` +- **Clone**, **Edit**, and **Remove**: copy, change, or delete the server. +- **Settings**: change the OAuth settings, headers, and other connection options. +- **Connection Info**: show details about the connection. This action shows only while the server is connected. -Replace `[tenant]` with your actual tenant name. For example, if your SailPoint URL is `https://acme.identitynow.com`, the full URL would be `https://acme.api.identitynow.com/latest/access-requests/mcp`. +The `--catalog` flag lets the Inspector save the changes you make in the UI back to the file. To load the file without changing it, use `--config` instead of `--catalog`. -:::note FedRAMP and data sovereignty -Customers with FedRAMP or data sovereignty requirements should continue using the tenant-specific URL instead of the global URL. +:::note Import the file into a running Inspector +If the Inspector is already open, you can import the file instead. Select **Add Servers ▾** in the top-right corner of the **Servers** page, then choose **client config**, and select `sailpoint-mcp-inspector.json`. ::: -## Step 3: Set Up Authentication +## Step 4: Connect to a Server -### Using the Global URL (OAuth Discovery) +1. On a SailPoint server card, select the toggle next to **Disconnected**. +2. When you connect to a server for the first time, the Inspector opens a browser window. Log in with your ISC credentials and approve the consent screen. If the tenant cannot be determined from your Client ID, you are prompted to enter your tenant name. -AI clients that support OAuth discovery via `.well-known` endpoints will **automatically discover** the authorization and token endpoints from the global MCP URL — no manual endpoint configuration is needed. +**When the connection succeeds:** -If your AI client cannot determine the tenant from your client ID, you will be prompted to enter your tenant name during the OAuth flow. +- The server card has a green border, and its status changes from **Disconnected** to **Connected**. +- The card shows the MCP protocol version of the server, for example `MCP 2025-11-25`. +- The top bar shows the name of the server and **Connected**, with the connection time. +- The **Messages** panel on the right shows the `initialize`, `notifications/initialized`, and `tools/list` messages, each marked **OK**. -If you need to configure OAuth endpoints manually, use these global URLs: +While one server is connected, the other server cards are dimmed. To use another server, turn off the toggle on the connected card, then turn on the toggle on the other card. -| Endpoint | URL | -|---|---| -| Authorization | `https://login.sailpoint.com/oauth/authorize` | -| Token | `https://api.identitynow.com/oauth/token` | +Tokens refresh automatically after you sign in. -### Using the Tenant-Specific URL (Bearer Token) +## Step 5: List Available Tools -If you are using the tenant-specific URL, you can authenticate with a bearer token directly: +1. Connect to a server, as described in [Step 4](#step-4-connect-to-a-server). +2. Select **Tools** at the top of the page. -1. Follow our [Authentication documentation](../../api/authentication.md) to generate an access token -2. Ensure your token has the necessary permissions for MCP operations +The **Tools** page shows the tools of the connected server, with their descriptions and parameters. Each server returns only its own tools. To see the tools of the other server, connect to that server and open **Tools** again. -In the MCP Inspector: +The Access Requests server provides four tools, and the Identity Intelligence server provides two. For details, refer to [Available Tools](./available-tools.mdx). -1. Select the **Authentication** tab -2. Set the following values: - - **Header Name**: `Authorization` - - **Bearer Token**: Paste your access token (include the "Bearer " prefix) +## Manual Setup -### Connect to the Server +Use these steps only if you cannot use the config file from [Step 2](#step-2-prepare-the-sailpoint-config-file). -Select **Connect** to establish the connection. +
+Add a server manually -**Success indicators:** -- The connection status should show as "Connected" -- You'll see the main MCP Inspector interface -- No error messages appear in the console +1. Launch the Inspector without a config file: -![MCP Connected](./img/mcp-connected.png) + ```bash + npx @modelcontextprotocol/inspector@latest + ``` -## Step 4: Test Your Connection +2. On the **Servers** page, select **Add Servers ▾** in the top-right corner, then choose **Add manually**. +3. Set the **Transport Type** to `Streamable HTTP`. +4. Enter the server **URL**: -### List Available Tools + | Server | Global URL | + |---|---| + | Access Requests | `https://mcp.sailpoint.com/latest/access-requests/mcp` | + | Identity Intelligence | `https://mcp.sailpoint.com/latest/intelligence/mcp` | -Select **List Tools** to retrieve available MCP tools from the SailPoint server. +5. Save the server. +6. On the server card, select **Settings** and expand **OAuth Settings**. Then set: + - **Client ID**: the Client ID from [Step 1](#step-1-create-an-api-client-in-isc) + - **Client Secret**: leave blank (the ISC client is a public client that uses PKCE) + - **Scopes**: the scope of the server, as listed in [Step 1](#step-1-create-an-api-client-in-isc) (space-separated, no commas) +7. Leave **Enterprise-managed authorization** unchecked. +8. To add another server, repeat steps 2 to 7 with that server's URL. -**If successful, you will see:** -- A list of available tools with descriptions -- Tool names, parameters, and usage information -- No error messages or timeouts +Then continue to [Step 4](#step-4-connect-to-a-server). -The SailPoint MCP server currently provides four core tools. +The Inspector finds SailPoint's authorization and token endpoints from the server's `.well-known` metadata. If you must enter the endpoints by hand, use these URLs: -![Available Tools](./img/mcp-tools.png) +| Endpoint | URL | +|---|---| +| Authorization | `https://login.sailpoint.com/oauth/authorize` | +| Token | `https://api.identitynow.com/oauth/token` | + +
+ +
+Use the tenant-specific URL with a bearer token + +Customers with FedRAMP or data sovereignty requirements must use the tenant-specific URL instead of the global URL: + +| Server | Tenant-specific URL | +|---|---| +| Access Requests | `https://[tenant].api.identitynow.com/latest/access-requests/mcp` | +| Identity Intelligence | `https://[tenant].api.identitynow.com/latest/intelligence/mcp` | + +Replace `[tenant]` with your tenant name. For example, if your SailPoint URL is `https://acme.identitynow.com`, the Access Requests URL is `https://acme.api.identitynow.com/latest/access-requests/mcp`. + +With the tenant-specific URL, you authenticate with a bearer token: + +1. Generate an access token. For instructions, refer to the [Authentication documentation](../../api/authentication.md). +2. Make sure that the token has the necessary permissions for the tools that you want to use. +3. In `sailpoint-mcp-inspector.json`, change each URL to the tenant-specific URL. Replace each `oauth` block with a `headers` block that contains your token: + + ```json + { + "mcpServers": { + "sailpoint-access-requests": { + "type": "streamable-http", + "url": "https://[tenant].api.identitynow.com/latest/access-requests/mcp", + "headers": { + "Authorization": "Bearer YOUR_ACCESS_TOKEN" + } + }, + "sailpoint-identity-intelligence": { + "type": "streamable-http", + "url": "https://[tenant].api.identitynow.com/latest/intelligence/mcp", + "headers": { + "Authorization": "Bearer YOUR_ACCESS_TOKEN" + } + } + } + } + ``` + +4. Launch the Inspector with the file, as described in [Step 3](#step-3-launch-the-mcp-inspector). + +If you added the servers manually, select **Settings** on each server card instead, and add an `Authorization` header with the value `Bearer YOUR_ACCESS_TOKEN`. + +
## Next Steps @@ -136,4 +240,4 @@ Now that you have a working connection, you can: - **Explore available tools** - Learn about each tool's capabilities in our [Available Tools](./available-tools.mdx) guide - **Test tool execution** - Try running tools with different parameters to understand their behavior -- **Build integrations** - Use the MCP protocol in your AI applications to automate SailPoint operations \ No newline at end of file +- **Build integrations** - Use the MCP protocol in your AI applications to automate SailPoint operations diff --git a/docs/extensibility/model-context-protocol/integrations/claude-code.md b/docs/extensibility/model-context-protocol/integrations/claude-code.md index 26256a5067b4c..50d012f47a7dd 100644 --- a/docs/extensibility/model-context-protocol/integrations/claude-code.md +++ b/docs/extensibility/model-context-protocol/integrations/claude-code.md @@ -13,55 +13,53 @@ tags: ['MCP', 'Claude Code', 'CLI'] This guide will walk you through the process of connecting the SailPoint MCP server using Claude Code. +Claude Code connects to the SailPoint MCP Server using OAuth 2.1 with PKCE by way of the `mcp-remote` helper, so you no longer need to generate or paste in a long-lived authentication token. Instead, you supply a Client ID and Claude Code handles the login and consent flow for you in the browser. + :::warning Before configuring this integration, please confirm with your organization's administrator whether the integration is allowed with this AI provider. SailPoint does not bear any responsibility in this regard. ::: +:::note +Claude Code's built-in remote MCP OAuth (`claude mcp add --transport http`) currently requires Dynamic Client Registration, which the SailPoint MCP Server does not support. This guide uses `mcp-remote` with a pre-registered Client ID instead. +::: + ## Prerequisites Before you begin, ensure you have the following: - [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) installed and configured on your system - Node.js and npm installed (required for the `npx` command) -- Access credentials for your MCP server +- An ISC tenant with the MCP Access Requests feature enabled +- Permission to create an API client in ISC, or a Client ID provided by your administrator - Basic familiarity with command line operations -## Step 1: Set Up Authentication - -First, you'll need to configure your authentication token as an environment variable. This keeps your credentials secure and separate from your configuration. - -### Setting the Environment Variable - -**On macOS/Linux:** - -```bash -export AUTH_TOKEN="your_actual_token_here" -``` +:::note +The global MCP URL is not available for FedRAMP tenants or tenants with data sovereignty requirements. Those environments should continue to use their tenant-specific URL. +::: -**On Windows (Command Prompt):** +## Step 1: Create an API client in ISC -```cmd -set AUTH_TOKEN=your_actual_token_here -``` +In ISC, go to **Admin > Security Settings > API Management** and create a new API client: -**On Windows (PowerShell):** +1. Set the client type to **Public**. +2. Enable the **Authorization Code** and **Refresh Token** grant types. +3. Set the **Redirect URL** to `http://localhost:3334/oauth/callback`. +4. Set the **Scope** to `sp:scopes:all`. -```powershell -$env:AUTH_TOKEN="your_actual_token_here" -``` +Save the client and copy the **Client ID** — you will need it in the next step. -:::tip -To make the environment variable persistent across sessions, add it to your shell profile (`.bashrc`, `.zshrc`, etc.) or system environment variables. +:::note +`3334` is the default local port `mcp-remote` uses for the OAuth callback. If that port is already in use, `mcp-remote` will pick a random port and authentication can fail with a redirect URI mismatch. To keep the redirect URL stable, pass a fixed port as an argument after the URL (as shown below) and register the matching `http://localhost:/oauth/callback` URL on the API client. ::: ## Step 2: Add the MCP Server to Claude Code -Once your authentication is configured, you can add the MCP server to Claude Code using the following command: +Add the server with the command below. It uses the global MCP URL, which works for all tenants without any tenant-specific changes. -The command below uses the global MCP URL, which works for all tenants without any tenant-specific changes. +**Replace `your-client-id` with the Client ID from Step 1.** ```bash -claude mcp add-json sailpoint-mcp '{"type":"stdio","command":"npx","args":["mcp-remote@latest","https://mcp.sailpoint.com/latest/access-requests/mcp","--header","Authorization: Bearer ${AUTH_TOKEN}"]}' +claude mcp add-json sailpoint-mcp '{"type":"stdio","command":"npx","args":["mcp-remote@latest","https://mcp.sailpoint.com/latest/access-requests/mcp","3334","--static-oauth-client-info","{\"client_id\":\"your-client-id\"}"]}' ``` ### Using the --scope Flag @@ -81,16 +79,13 @@ Let's break down the base command: - `"args": [...]` - Array of arguments passed to the npx command: - `"mcp-remote@latest"` - The MCP remote package (always uses latest version) - `"https://mcp.sailpoint.com/latest/access-requests/mcp"` - The global MCP server endpoint - - `"--header"` - Specifies a custom header for authentication - - `"Authorization: Bearer ${AUTH_TOKEN}"` - The authorization header using your environment variable - -## Step 3: Verify the Connection + - `"3334"` - The local port `mcp-remote` listens on for the OAuth callback (must match the redirect URL registered in Step 1) + - `"--static-oauth-client-info"` - Tells `mcp-remote` to use your pre-registered Client ID instead of dynamic client registration + - `"{\"client_id\":\"your-client-id\"}"` - The pre-registered Client ID from Step 1 -Here's an improved version of that snippet: +## Step 3: Authenticate and Verify the Connection -**Verifying the MCP Server Installation** - -After adding the MCP server, verify the installation by starting a new Claude session: +After adding the MCP server, start a new Claude session: ```bash claude @@ -102,14 +97,18 @@ Once the session starts, use the MCP command to connect to your server: /mcp ``` -Claude will attempt to establish a connection to all configured MCP servers. Upon successful connection, you can: +On first connect, `mcp-remote` opens a browser window to complete the OAuth flow: + +1. Log in with your ISC credentials (SSO is supported if it is configured for your tenant). +2. Approve the consent screen. +3. You are connected — tokens refresh automatically, so you will not need to re-enter your credentials mid-session. + +If the connection is successful, you should see `sailpoint-mcp` listed among your active MCP servers, confirming that the setup was completed correctly. From the `/mcp` menu you can: - Browse the tools and their descriptions - Verify that your `sailpoint-mcp` server appears in the configured servers list - Test the server's functionality -If the connection is successful, you should see `sailpoint-mcp` listed among your active MCP servers, confirming that the setup was completed correctly. - ## **Try it out!** You can now ask Claude Code questions like "What can I request access to?” or “What is the status of my access request?” or “Cancel access request XYZ” diff --git a/docs/extensibility/model-context-protocol/integrations/claude-desktop.md b/docs/extensibility/model-context-protocol/integrations/claude-desktop.md index 3ab6c0d671a91..e231ea0df4f71 100644 --- a/docs/extensibility/model-context-protocol/integrations/claude-desktop.md +++ b/docs/extensibility/model-context-protocol/integrations/claude-desktop.md @@ -13,6 +13,8 @@ tags: ['MCP', 'Claude Desktop'] This guide will walk you through the process of connecting the SailPoint MCP server using Claude Desktop. +Claude Desktop connects to the SailPoint MCP Server as a custom connector using OAuth 2.1 with PKCE, so you no longer need to generate or paste in an authentication token. Instead, you supply a Client ID and Claude handles the login and consent flow for you. + :::warning Before configuring this integration, please confirm with your organization's administrator whether the integration is allowed with this AI provider. SailPoint does not bear any responsibility in this regard. ::: @@ -22,67 +24,56 @@ Before configuring this integration, please confirm with your organization's adm Before you begin, ensure you have the following: - [Claude Desktop](https://claude.ai/download) installed and configured on your system -- Access credentials for your MCP server - -## Step 1: Open claude desktop - -Open Claude Desktop and complete the normal setup. You will then be presented with the following screen: - -![Claude Desktop](../img/claude-desktop.png) +- A Claude Pro, Max, Team, or Enterprise plan (custom connectors are not available on the free plan) +- An ISC tenant with the MCP Access Requests feature enabled +- Permission to create an API client in ISC, or a Client ID provided by your administrator -## Step 2: Open claude desktop developer settings - -Select `Claude` in your menu bar, select `Settings` - -![Claude Developer Settings](../img/claude-desktop-settings.jpg) +:::note +The global MCP URL is not available for FedRAMP tenants or tenants with data sovereignty requirements. Those environments should continue to use their tenant-specific URL. +::: -Then select `Developer` +## Step 1: Create an API client in ISC -![Claude Developer](../img/claude-developer.png) +In ISC, go to **Admin > Security Settings > API Management** and create a new API client: -Finally, select `edit config` +1. Set the client type to **Public**. +2. Enable the **Authorization Code** and **Refresh Token** grant types. +3. Set the **Redirect URL** to `https://claude.ai/api/mcp/auth_callback`. +4. Set the **Scope** to `sp:scopes:all`. -![Claude Config](../img/claude-edit-config.png) +Save the client and copy the **Client ID** — you will need it in the next step. -This will take you to the Claude Desktop config file in your filesystem `claude_desktop_config.json`. Open this file in your preferred editor. +## Step 2: Add the SailPoint MCP Server as a custom connector -Copy and paste the following snippet. +1. Open Claude Desktop and go to **Settings > Connectors**. +2. Select **Add custom connector** at the bottom of the Connectors section. +3. Enter a name (for example, `SailPoint MCP`) and the global MCP URL: -**Replace `your_auth_token_here` with your authorization token.** + ``` + https://mcp.sailpoint.com/latest/access-requests/mcp + ``` -The configuration uses the global MCP URL, which works for all tenants without any tenant-specific changes. + The global MCP URL works for all tenants without any tenant-specific changes. Your tenant is identified automatically during authentication. If the tenant name cannot be detected, you will be prompted to enter it on first connect. +4. Expand **Advanced settings** and enter the **OAuth Client ID** from Step 1. Leave the **OAuth Client Secret** blank — the SailPoint API client is a public client. +5. Select **Add** to save the connector. -```json -{ - "mcpServers": { - "SailPoint MCP": { - "command": "npx", - "args": [ - "mcp-remote@latest", - "https://mcp.sailpoint.com/latest/access-requests/mcp", - "--debug", - "--header", - "Authorization: Bearer ${AUTH_TOKEN}" - ], - "env": { - "AUTH_TOKEN": "your_auth_token_here" - } - } - } -} -``` +## Step 3: Connect and authenticate -## **Restart claude and check for MCP tools** +1. In **Settings > Connectors**, find the SailPoint MCP connector and select **Connect**. +2. Claude opens a browser window to complete the OAuth flow: + 1. Log in with your ISC credentials (SSO is supported if it is configured for your tenant). + 2. Approve the consent screen. + 3. You are connected — tokens refresh automatically, so you will not need to re-enter your credentials mid-session. -1. This is required to pick up the new config +## **Check for MCP tools** -2. Select the Tools icon at the bottom of the new chat UI. You will see SailPoint MCP among the tools listed: +Select the Tools icon at the bottom of the new chat UI. You will see SailPoint MCP among the tools listed: - ![Claude Tools](../img/claude-tools.png) +![Claude Tools](../img/claude-tools.png) -3. Ensure all four tools are enabled: +Ensure the SailPoint access request tools are enabled: - ![Claude Tool Details](../img/claude-tool-details.png) +![Claude Tool Details](../img/claude-tool-details.png) ## **Try it out!** diff --git a/docs/extensibility/model-context-protocol/integrations/cursor.md b/docs/extensibility/model-context-protocol/integrations/cursor.md index 3f83ac1ac3cbf..5a8729d7ca817 100644 --- a/docs/extensibility/model-context-protocol/integrations/cursor.md +++ b/docs/extensibility/model-context-protocol/integrations/cursor.md @@ -13,44 +13,76 @@ tags: ['MCP', 'Cursor'] This guide will walk you through configuring Cursor to connect with the SailPoint Model Context Protocol (MCP) Server using the `mcp.json` configuration file. +Cursor connects to the SailPoint MCP Server natively using OAuth 2.1 with PKCE, so you no longer need to generate or paste in an authentication token. Instead, you supply a Client ID and Cursor handles the entire login and consent flow for you. + :::warning Before configuring this integration, please confirm with your organization's administrator whether the integration is allowed with this AI provider. SailPoint does not bear any responsibility in this regard. ::: ## Prerequisites -- [Cursor](https://cursor.com/downloads) installed -- Node.js and npm installed -- Access to a valid SailPoint MCP Server endpoint and an authentication token +- [Cursor](https://cursor.com/downloads) (v0.44+) installed +- An ISC tenant with the MCP Access Requests feature enabled +- Permission to create an API client in ISC, or a Client ID provided by your administrator + +:::note +The global MCP URL is not available for FedRAMP tenants or tenants with data sovereignty requirements. Those environments should continue to use their tenant-specific URL. +::: + +## Step 1: Create an API client in ISC + +In ISC, go to **Admin > Security Settings > API Management** and create a new API client: -## Step 1: Create `mcp.json` +1. Set the client type to **Public**. +2. Enable the **Authorization Code** and **Refresh Token** grant types. +3. Set the **Redirect URL**: + - Cursor 3.11 and later: `http://localhost:8787/callback` + - Earlier versions: `cursor://anysphere.cursor-mcp/oauth/callback` +4. Set the **Scope** to `sp:scopes:all`. -Cursor allows for deep links into its configuration. By clicking the button below, you will be asked to open the link in Cursor. This will take you to the MCP Server configuration with most of the configuration filled out for you. +Save the client and copy the **Client ID** — you will need it in the next step. -[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=SailPoint%20MCP&config=ewogICAgImNvbW1hbmQiOiAibnB4IiwKICAgICJlbnYiOiB7CiAgICAgICAgIkFVVEhfVE9LRU4iOiAieW91cl9hdXRoX3Rva2VuX2hlcmUiCiAgICB9LAogICAgImFyZ3MiOiBbCiAgICAgICAgIm1jcC1yZW1vdGVAbGF0ZXN0IiwKICAgICAgICAiaHR0cHM6Ly9tY3Auc2FpbHBvaW50LmNvbS9sYXRlc3QvYWNjZXNzLXJlcXVlc3RzL21jcCIsCiAgICAgICAgIi0tZGVidWciLAogICAgICAgICItLWhlYWRlciIsCiAgICAgICAgIkF1dGhvcml6YXRpb246IEJlYXJlciAke0FVVEhfVE9LRU59IgogICAgXQp9) +## Step 2: Add the SailPoint MCP Server to `mcp.json` -Once in Cursor, following the prompt to install the SailPoint MCP server and select install to continue. +Open `~/.cursor/mcp.json` (or use **Cursor Settings > MCP > Add**) and add the configuration below. -![cursor install](../img/cursor-install.png) +The configuration uses the global MCP URL (`https://mcp.sailpoint.com/latest/access-requests/mcp`), which works for all tenants without any tenant-specific changes. Your tenant is identified automatically during authentication. If the tenant name cannot be detected, you will be prompted to enter it on first connect. -## Step 2: Add your authentication token +```json +{ + "mcpServers": { + "sailpoint-access-requests": { + // highlight-next-line + "url": "https://mcp.sailpoint.com/latest/access-requests/mcp", + "auth": { + // highlight-next-line + "CLIENT_ID": "your-client-id", + "scopes": ["sp:scopes:all"] + } + } + } +} +``` -Click the edit icon next to the newly installed SailPoint MCP server. This will bring up the `mcp.json` file in the editor. +**Replace `your-client-id` with the Client ID from Step 1**, then save the file. -The configuration uses the global MCP URL (`https://mcp.sailpoint.com/latest/access-requests/mcp`), which works for all tenants without any tenant-specific changes. +## Step 3: Connect and authenticate -**Replace `your_auth_token_here` with your authorization token.** +Open **Cursor Settings > MCP** and click **Connect** next to the SailPoint MCP server. Cursor handles the entire OAuth flow: -Save the file. +1. A browser window opens. +2. Log in with your ISC credentials (SSO is supported if it is configured for your tenant). +3. Approve the consent screen. +4. You are connected — tokens refresh automatically, so you will not need to re-enter your credentials mid-session. -### Step 3: Verify the Connection +### Step 4: Verify the Connection Go back to the Cursor settings tab. 1. Open the Command Palette (`Cmd+Shift+P` on macOS or `Ctrl+Shift+P` on Windows/Linux). 2. Search for and select `View: Open MCP Settings`. -You will see that Cursor is connected and has four tools available. +You will see that Cursor is connected and has the SailPoint access request tools available. ![cursor tools](../img/cursor-connected.png) diff --git a/docs/extensibility/model-context-protocol/integrations/vs-code.md b/docs/extensibility/model-context-protocol/integrations/vs-code.md index 5ac5310fa41df..c27bda846dbb6 100644 --- a/docs/extensibility/model-context-protocol/integrations/vs-code.md +++ b/docs/extensibility/model-context-protocol/integrations/vs-code.md @@ -13,18 +13,41 @@ tags: ['MCP', 'VS Code'] This guide will walk you through configuring Visual Studio Code to connect with the SailPoint Model Context Protocol (MCP) Server using the `mcp.json` configuration file. +VS Code connects to the SailPoint MCP Server using OAuth 2.1 with PKCE, so you no longer need to generate or paste in an authentication token. Instead, you supply a Client ID and VS Code handles the login and consent flow for you. + :::warning Before configuring this integration, please confirm with your organization's administrator whether the integration is allowed with this AI provider. SailPoint does not bear any responsibility in this regard. ::: ## Prerequisites -- [Visual Studio Code](https://code.visualstudio.com/) installed +- [Visual Studio Code](https://code.visualstudio.com/) (v1.101+) installed - [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) extension installed and enabled -- Node.js and npm installed -- Access to a valid SailPoint MCP Server endpoint and an authentication token +- An ISC tenant with the MCP Access Requests feature enabled +- Permission to create an API client in ISC, or a Client ID provided by your administrator + +:::note +The global MCP URL is not available for FedRAMP tenants or tenants with data sovereignty requirements. Those environments should continue to use their tenant-specific URL. +::: + +## Step 1: Create an API client in ISC + +In ISC, go to **Admin > Security Settings > API Management** and create a new API client: + +1. Set the client type to **Public**. +2. Enable the **Authorization Code** and **Refresh Token** grant types. +3. Set the **Redirect URLs** to both of the URLs VS Code uses for its OAuth callback: + - `http://127.0.0.1:33418` + - `https://vscode.dev/redirect` +4. Set the **Scope** to `sp:scopes:all`. -## Step 1: Enable MCP Support in VS Code +Save the client and copy the **Client ID** — you will need it in Step 3. + +:::note +VS Code uses the loopback port `33418` for its OAuth callback by default. If that port is unavailable, VS Code may fall back to a different port and authentication can fail with a redirect URI mismatch. If you hit this, set a fixed `callbackPort` in the server's `oauth` configuration and register the matching redirect URL on the API client. +::: + +## Step 2: Enable MCP Support in VS Code Before configuring the server, make sure MCP support is enabled in your VS Code settings: @@ -38,50 +61,44 @@ Before configuring the server, make sure MCP support is enabled in your VS Code This setting allows VS Code to discover and connect to MCP servers defined in your `mcp.json` file. -## Step 2: Create or Update `mcp.json` +## Step 3: Add the SailPoint MCP Server to `mcp.json` -1. Open VS Code. -2. Open the Command Palette (`Cmd+Shift+P` on macOS or `Ctrl+Shift+P` on Windows/Linux). -3. Search for and select `MCP: Open User Configuration`. -4. Add the following configuration to `mcp.json`: +1. Open the Command Palette (`Cmd+Shift+P` on macOS or `Ctrl+Shift+P` on Windows/Linux). +2. Search for and select `MCP: Open User Configuration`. +3. Add the following configuration to `mcp.json`: -The configuration below uses the global MCP URL, which works for all tenants without any tenant-specific changes. +The configuration uses the global MCP URL (`https://mcp.sailpoint.com/latest/access-requests/mcp`), which works for all tenants without any tenant-specific changes. Your tenant is identified automatically during authentication. If the tenant name cannot be detected, you will be prompted to enter it on first connect. ```json { "servers": { - "SailPoint MCP": { - "command": "npx", - "args": [ - "mcp-remote@latest", + "sailpoint-access-requests": { + "type": "http", + // highlight-next-line + "url": "https://mcp.sailpoint.com/latest/access-requests/mcp", + "oauth": { // highlight-next-line - "https://mcp.sailpoint.com/latest/access-requests/mcp", - "--debug", - "--header", - "Authorization: Bearer ${input:AUTH_TOKEN}" - ] - } - }, - "inputs": [ - { - "type": "promptString", - "id": "AUTH_TOKEN", - "description": "Enter your AUTH TOKEN:", - "password": true + "clientId": "your-client-id" + } } - ] + } } ``` -## Step 3: Connect to the MCP Server +**Replace `your-client-id` with the Client ID from Step 1**, then save the file. + +## Step 4: Connect and authenticate 1. Open the Command Palette. -2. Search for and select `MCP: Open User Configuration` -3. Select `Start` above the configuration for "SailPoint MCP". +2. Search for and select `MCP: Open User Configuration`. +3. Select `Start` above the configuration for "sailpoint-access-requests". ![vs code mcp](../img/vs-code-mcp-json.png) -4. When prompted, enter your authentication token. +4. VS Code opens a browser window to complete the OAuth flow: + 1. Log in with your ISC credentials (SSO is supported if it is configured for your tenant). + 2. Approve the consent screen. + 3. You are connected — tokens refresh automatically, so you will not need to re-enter your credentials mid-session. -### Step 4: Verify the Connection +### Step 5: Verify the Connection Once connected, you should be able to interact with the SailPoint MCP Server directly from VS Code. diff --git a/static/files/sailpoint-mcp-inspector.json b/static/files/sailpoint-mcp-inspector.json new file mode 100644 index 0000000000000..ec06677701480 --- /dev/null +++ b/static/files/sailpoint-mcp-inspector.json @@ -0,0 +1,20 @@ +{ + "mcpServers": { + "sailpoint-access-requests": { + "type": "streamable-http", + "url": "https://mcp.sailpoint.com/latest/access-requests/mcp", + "oauth": { + "clientId": "YOUR_CLIENT_ID", + "scopes": "sp:scopes:all" + } + }, + "sailpoint-identity-intelligence": { + "type": "streamable-http", + "url": "https://mcp.sailpoint.com/latest/intelligence/mcp", + "oauth": { + "clientId": "YOUR_CLIENT_ID", + "scopes": "sp:identity-sec-intel:read" + } + } + } +}