Connect Claude Desktop 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. Claude Desktop will open your browser to complete authentication.
:::

### Configuring Scopes

The `OAUTH_SCOPES` environment variable controls what permissions Claude 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: Restart Claude Desktop

After saving the configuration file:

1. Completely quit Claude Desktop (don't just close the window)
2. Relaunch Claude Desktop

Claude will automatically detect the new MCP server configuration.

## Step 4: Complete the OAuth Flow

The first time Claude Desktop connects to your Hanzo IAM MCP server:

1. Claude Desktop 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 Claude Desktop
4. The consent screen shows 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 Claude Desktop - 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 asking Claude to interact with Hanzo IAM:

**Example prompts to try:**

- "List all applications in Hanzo IAM"
- "Show me details about the application named 'my-app'"
- "Create a new application called 'test-app' in organization 'my-org'"

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

**Expected output for "List all applications":**

```text
I found the following applications in your Hanzo IAM instance:

1. claude-desktop-mcp (Claude Desktop MCP Client)
2. app-built-in (Hanzo IAM)
...

## Troubleshooting

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

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

**Solution**:

- Verify the URL in your `claude_desktop_config.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