Connect Cursor to MCP

{
  "mcpServers": {
    "iam": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-oauth",
        "https://your-iam.com/api/mcp"
      ],
      "env": {
        "OAUTH_CLIENT_ID": "your-client-id",
        "OAUTH_SCOPES": "read:application write:application openid profile email"
      }
    }
  }
}

Replace the following placeholders:

- `your-iam.com` → Your Hanzo IAM instance domain
- `your-client-id` → The Client ID from Step 1

:::note
The `@modelcontextprotocol/server-oauth` package handles OAuth flows automatically. Cursor will open your browser to complete authentication.
:::

### Configuring Scopes

The `OAUTH_SCOPES` environment variable controls what permissions Cursor's AI has. Common scopes include:

- `read:application` - View applications
- `write:application` - Create, update, delete applications
- `read:user` - View users
- `write:user` - Create, update, delete users
- `openid profile email` - Basic user information (required for OAuth)

See [Authorization and Scopes](/docs/how-to-connect/mcp/authorization) for the complete list of available scopes.

## Step 3: Reload Cursor

After saving the configuration:

1. Reload Cursor IDE (Cmd+Shift+P or Ctrl+Shift+P → "Developer: Reload Window")
2. Alternatively, restart Cursor completely

Cursor will automatically detect and load the new MCP server configuration.

## Step 4: Complete the OAuth Flow

When Cursor first connects to your Hanzo IAM MCP server:

1. Cursor will automatically open your default web browser
2. You'll see the Hanzo IAM login page (if not already logged in)
3. After logging in, you'll see a **Consent Screen** asking you to authorize Cursor
4. The consent screen displays the requested scopes (permissions)
5. Click **Authorize** to grant access
6. Your browser will redirect to `http://127.0.0.1:<port>/callback` and show a success message
7. Return to Cursor - the connection is now established

:::tip
The OAuth token is securely stored by the MCP OAuth helper. You won't need to re-authorize unless you revoke the token or change scopes.
:::

## Step 5: Verify the Connection

Test the connection by using Cursor's AI features to interact with Hanzo IAM:

**Example prompts to try in Cursor's chat:**

- "Using the Hanzo IAM MCP server, list all applications"
- "Show me details about the application named 'my-app' from Hanzo IAM"
- "Create a new Hanzo IAM application called 'test-app' in organization 'my-org'"

Cursor's AI will use the MCP tools to execute these commands. You should see responses with data from your Hanzo IAM instance.

**Expected output:**

```text
I've queried the Hanzo IAM MCP server and found the following applications:

1. cursor-mcp (Cursor IDE MCP Client)
2. app-built-in (Hanzo IAM)
...

## Troubleshooting

### Issue: "MCP server not found" in Cursor

**Cause**: The configuration file might not be in the correct location or has syntax errors.

**Solution**:

- Verify the file path for your operating system
- Check that the JSON is valid (no trailing commas, proper quotes)
- Reload Cursor after making changes

### Issue: "Unable to connect to MCP server"

**Cause**: The MCP server URL might be incorrect or unreachable.

**Solution**:

- Verify the URL in your `mcp.json` is correct
- Ensure your Hanzo IAM instance is running and accessible
- Check for HTTPS/HTTP mismatch (use HTTPS in production)

### Issue: "Redirect URI mismatch" error during OAuth

**Cause**: The callback URL doesn't match the configured Redirect URI in Hanzo IAM.

**Solution**:

- In Hanzo IAM, ensure your application has these redirect URIs:

  ```text
  http://127.0.0.1:*/callback
  http://localhost:*/callback