HomeUse CasesConceptsConfig GuidesDeveloper GuidesAPI Reference
Content

Tenant Setup

IBM Verify MCP Server - Tenant Setup Guide

Overview

This guide walks you through setting up your IBM Verify tenant before installing and running the MCP Server. Follow these steps in order to ensure proper configuration.

📖 New to IBM Verify MCP Server? Start with the Overview to understand what the MCP Server does and how it works.

Prerequisites

MCP Server

The following prerequisites are required to set up and run the MCP Server:

  1. Admin access to the IBM Verify tenant.
  2. A Kubernetes cluster or VM to deploy and run the MCP Server.
  3. Internet connectivity from the Kubernetes cluster or VM.
  4. Nginx setup when deploying the MCP Server on a VM.
  5. Docker client installed and configured.

MCP Client

The following prerequisites are required to set up and run the MCP Client:

  1. An MCP-compatible client, such as IBM Bob, Claude, or another supported MCP client.
  2. Python installed with:
    • uv
    • fastmcp-remote

MCP Server Resource Requirements

The following are the recommended minimum resources for the MCP Server to support 400+ concurrent users:

ResourceRequirement
CPU1 Core
Memory1 GB

Note: Resource requirements may vary depending on the number and type of tools being invoked, request frequency, session management, and overall workload.

What You'll Configure

This setup process creates three components in your IBM Verify tenant:

  1. Actor Application - OAuth client for the MCP Server itself
  2. Subject Application - OAuth client for user authentication
  3. STS Client - Security Token Service for token exchange

These components enable secure, user-delegated access to IBM Verify APIs through the MCP Server.

Step 1: Verify Tenant Access

Ensure you have:

  • ✅ Active IBM Verify tenant
  • ✅ Administrator access to the tenant
  • ✅ Tenant URL (e.g., https://your-tenant.verify.ibm.com)

Step 2: Create API Client for Setup

The automated setup script requires an API client with specific permissions.

2.1 Configure API Client

  1. Log in to IBM Verify Admin Console
  2. Go to Security → API access
  3. Click Add API client
  4. Enter name and description as suggested:
    Name: MCP Server Setup Client
    Description: API client for automated MCP Server tenant configuration

2.2 Assign Required Entitlements

The API client MUST have these two entitlements:

EntitlementDescription
manageAppAccessAdmin (Manage application lifecycle)Required to create OAuth applications
manageSTSClients (Manage STS clients and token types)Required to create Token Exchange client

How to assign:

  1. In the API client configuration, find the Entitlements section
  2. Search and select: manageAppAccessAdmin (Manage application lifecycle)
  3. Search and select: manageSTSClients (Manage STS clients and token types)
  4. Click Save

2.3 Save Credentials

After creating the API client, you receive the following:

  • Client ID: Copy and save securely
  • Client Secret: Copy and save securely

⚠ IMPORTANT: Securely note down all the client Id and client secret for Verify mcp server deployment.

Step 3: Prepare Your System

Ensure your local machine has:

  • ✅ bash shell (Linux, macOS, or WSL on Windows)
  • ✅ curl command-line tool
  • ✅ Network access to your IBM Verify tenant

Verify requirements:

# Check bash
bash --version

# Check curl
curl --version

Step 4: Create Setup Script

Create the automated setup script on your local machine:

# Create a directory for MCP Server setup
mkdir -p ~/mcp-server-setup
cd ~/mcp-server-setup

# Create the script file
cat > setup-verify-tenant.sh << 'EOF'
#!/bin/bash

##################################################################################
## This script is used to configure the Applications and STS client on IBM Verify Tenant to use the MCP Server
## Requirements:- Provide the Tenant URL and the API client credentials
##  - API Client needs to have the following entitlements
##    - manageAppAccessAdmin (Manage application lifecycle)
##    - manageSTSClients (Manage STS clients and token types)
##################################################################################

set -e

echo "===================================================================================="
echo "IBM Verify MCP Server - Tenant Setup Script"
echo "===================================================================================="
echo ""
echo "This script configures your IBM Verify tenant for use with the MCP Server by:"
echo "  1. Creating two OAuth applications (Actor and Subject)"
echo "  2. Setting up a Token Exchange (STS) client"
echo "  3. Generating all necessary credentials for your MCP Server configuration"
echo ""
echo "Requirements:"
echo "  - IBM Verify tenant URL"
echo "  - API Client credentials with the following entitlements:"
echo "    ‱ manageAppAccessAdmin (Manage application lifecycle)"
echo "    ‱ manageSTSClients (Manage STS clients and token types)"
echo "    (API client can be created in Admin Console: Security -> API access)"
echo ""
echo "===================================================================================="
echo ""

# Prompt for IBM Verify tenant URL
echo -n "Enter IBM Verify tenant URL: "
read TENANT_URL_INPUT

# Normalize TENANT_URL: add https:// if missing, remove trailing /
if [[ ! "$TENANT_URL_INPUT" =~ ^https?:// ]]; then
    TENANT_URL="https://${TENANT_URL_INPUT}"
else
    TENANT_URL="$TENANT_URL_INPUT"
fi
# Remove trailing slash if present
TENANT_URL="${TENANT_URL%/}"

# Prompt for API Client ID
echo -n "Enter API Client ID: "
read CLIENT_ID

# Prompt for API Client Secret (hidden input)
echo -n "Enter API Client Secret: "
stty -echo
read CLIENT_SECRET
stty echo
echo ""

echo ""
echo "Configuration:"
echo "  Tenant URL: $TENANT_URL"
echo "  Client ID: $CLIENT_ID"
echo ""

# Obtain access token
echo "Obtaining access token..."
TOKEN_RESPONSE=$(curl -s --request POST \
  --url "${TENANT_URL}/v1.0/endpoint/default/token" \
  --header 'accept: application/json' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data "client_id=${CLIENT_ID}" \
  --data "client_secret=${CLIENT_SECRET}" \
  --data scope=openid)

# Extract access token from response
ACCESS_TOKEN=$(echo "$TOKEN_RESPONSE" | grep -o '"access_token":"[^"]*"' | cut -d'"' -f4)

if [ -z "$ACCESS_TOKEN" ]; then
    echo "Error: Failed to obtain access token"
    echo "Response: $TOKEN_RESPONSE"
    exit 1
fi

echo "Access token obtained successfully"
echo ""

# Onboard application
echo "Onboarding application..."
APP_RESPONSE=$(curl -s --request POST \
  --url "${TENANT_URL}/v1.0/applications" \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '
  {
    "visibleOnLaunchpad": true,
    "customization": {
        "themeId": "default"
    },
    "name": "IBM Verify MCP Server Actor",
    "applicationState": true,
    "description": "The template to access Connect type of application.",
    "templateId": "998",
    "owners": [],
    "provisioning": {},
    "attributeMappings": [],
    "providers": {
        "sso": {
        "userOptions": "oidc"
        },
        "oidc": {
        "properties": {
            "doNotGenerateClientSecret": "false",
            "additionalConfig": {
            "oidcv3": true,
            "requestObjectParametersOnly": "false",
            "requestObjectSigningAlg": "RS256",
            "requestObjectRequireExp": "true",
            "certificateBoundAccessTokens": "false",
            "dpopBoundAccessTokens": "false",
            "validateDPoPProofJti": "false",
            "dpopProofSigningAlg": "RS256",
            "authorizeRspSigningAlg": "RS256",
            "authorizeRspEncryptionAlg": "none",
            "authorizeRspEncryptionEnc": "none",
            "responseTypes": [],
            "responseModes": [],
            "clientAuthMethod": "default",
            "requirePushAuthorize": "false",
            "allowedClientAssertionVerificationKeys": [],
            "requestObjectMaxExpFromNbf": 1800,
            "restrictAuthDetailTypes": true,
            "ignoreUnknownAuthDetailTypes": true,
            "exchangeForSSOSessionOption": "default",
            "logoutOption": "none",
            "subjectTokenTypes": [
                "urn:ietf:params:oauth:token-type:access_token"
            ],
            "actorTokenTypes": [
                "urn:ietf:params:oauth:token-type:access_token"
            ],
            "requestedTokenTypes": [
                "urn:ietf:params:oauth:token-type:access_token"
            ],
            "actorTokenRequired": false,
            "useUserDefaultEntitlements": false,
            "tctxMapping": ""
            },
            "generateRefreshToken": "false",
            "renewRefreshToken": "true",
            "idTokenEncryptAlg": "none",
            "idTokenEncryptEnc": "none",
            "grantTypes": {
            "authorizationCode": "false",
            "clientCredentials": "true",
            "ropc": "false",
            "tokenExchange": "false",
            "deviceFlow": "false",
            "jwtBearer": "false",
            "policyAuth": "false"
            },
            "accessTokenExpiry": 3600,
            "refreshTokenExpiry": 86400,
            "idTokenSigningAlg": "RS256",
            "redirectUris": []
        },
        "token": {
            "accessTokenType": "default"
        },
        "grantProperties": {
            "generateDeviceFlowQRCode": "false"
        },
        "requirePkceVerification": "true",
        "consentAction": "always_prompt",
        "scopes": [],
        "restrictEntitlements": true,
        "entitlements": []
        },
        "saml": {
        "properties": {
            "companyName": "IBM Verify"
        }
        }
    },
    "apiAccessClients": []
  }')


# Extract application ID from response
ACTOR_APP_ID=$(echo "$APP_RESPONSE" | grep -o '"href":"/appaccess/v1.0/applications/[0-9]\+"' | sed 's/.*\/applications\///' | tr -d '"')

if [ -z "$ACTOR_APP_ID" ]; then
    echo "Error: Failed to extract application ID"
    echo "Response: $APP_RESPONSE"
    exit 1
fi

echo "Application onboarded successfully"
echo "Actor Application ID: $ACTOR_APP_ID"
echo ""

# Retrieve application details to get client credentials
echo "Retrieving application credentials..."
APP_DETAILS_RESPONSE=$(curl -s --request GET \
  --url "${TENANT_URL}/v1.0/applications/${ACTOR_APP_ID}" \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}")

# Extract client ID and client secret from response
ACTOR_APP_CLIENT_ID=$(echo "$APP_DETAILS_RESPONSE" | grep -o '"clientId":"[^"]*"' | head -1 | cut -d'"' -f4)
ACTOR_APP_CLIENT_SECRET=$(echo "$APP_DETAILS_RESPONSE" | grep -o '"clientSecret":"[^"]*"' | head -1 | cut -d'"' -f4)

if [ -z "$ACTOR_APP_CLIENT_ID" ] || [ -z "$ACTOR_APP_CLIENT_SECRET" ]; then
    echo "Error: Failed to extract client credentials"
    echo "Response: $APP_DETAILS_RESPONSE"
    exit 1
fi

echo "Application credentials retrieved successfully"
echo "Actor Application Client ID: $ACTOR_APP_CLIENT_ID"
echo "Actor Application Client Secret: $ACTOR_APP_CLIENT_SECRET"
echo ""

# Onboard Subject application
echo "Onboarding Subject application..."
SUBJECT_APP_RESPONSE=$(curl -s --request POST \
  --url "${TENANT_URL}/v1.0/applications" \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data "
  {
	\"visibleOnLaunchpad\": true,
	\"customization\": {
		\"themeId\": \"default\"
	},
	\"name\": \"MCP Server Subject\",
	\"applicationState\": true,
	\"description\": \"The template to access Connect type of application.\",
	\"templateId\": \"998\",
	\"provisioning\": {},
	\"providers\": {
		\"sso\": {
			\"userOptions\": \"oidc\"
		},
		\"oidc\": {
			\"properties\": {
				\"doNotGenerateClientSecret\": \"false\",
				\"additionalConfig\": {
					\"oidcv3\": true,
					\"requestObjectParametersOnly\": \"false\",
					\"requestObjectSigningAlg\": \"RS256\",
					\"requestObjectRequireExp\": \"true\",
					\"certificateBoundAccessTokens\": \"false\",
					\"dpopBoundAccessTokens\": \"false\",
					\"validateDPoPProofJti\": \"false\",
					\"dpopProofSigningAlg\": \"RS256\",
					\"authorizeRspSigningAlg\": \"RS256\",
					\"authorizeRspEncryptionAlg\": \"none\",
					\"authorizeRspEncryptionEnc\": \"none\",
					\"responseTypes\": [
						\"none\",
						\"code\"
					],
					\"responseModes\": [
						\"query\",
						\"fragment\",
						\"form_post\",
						\"query.jwt\",
						\"fragment.jwt\",
						\"form_post.jwt\"
					],
					\"clientAuthMethod\": \"default\",
					\"requirePushAuthorize\": \"false\",
					\"allowedClientAssertionVerificationKeys\": [],
					\"requestObjectMaxExpFromNbf\": 1800,
					\"restrictAuthDetailTypes\": true,
					\"ignoreUnknownAuthDetailTypes\": true,
					\"exchangeForSSOSessionOption\": \"default\",
					\"logoutOption\": \"none\",
					\"subjectTokenTypes\": [
						\"urn:ietf:params:oauth:token-type:access_token\"
					],
					\"actorTokenTypes\": [
						\"urn:ietf:params:oauth:token-type:access_token\"
					],
					\"requestedTokenTypes\": [
						\"urn:ietf:params:oauth:token-type:access_token\"
					],
					\"actorTokenRequired\": false,
					\"authorizeRequestMap\": [],
					\"authorizeResponseMap\": [],
					\"tokenRequestMap\": [],
					\"tokenResponseMap\": [],
					\"refreshIntrospectMapClaimNames\": [
						\"may_act\"
					],
					\"refreshAttributeMapClaimNames\": [],
					\"requireConsentAttributeMapClaimNames\": [],
					\"suppressDefaultClaims\": false,
					\"useUserDefaultEntitlements\": false,
					\"tctxMapping\": \"\"
				},
				\"generateRefreshToken\": \"true\",
				\"renewRefreshToken\": \"true\",
				\"idTokenEncryptAlg\": \"none\",
				\"idTokenEncryptEnc\": \"none\",
				\"grantTypes\": {
					\"authorizationCode\": \"true\",
					\"implicit\": \"false\",
					\"clientCredentials\": \"false\",
					\"ropc\": \"false\",
					\"tokenExchange\": \"false\",
					\"deviceFlow\": \"false\",
					\"jwtBearer\": \"false\",
					\"policyAuth\": \"false\"
				},
				\"accessTokenExpiry\": 3600,
				\"refreshTokenExpiry\": 86400,
				\"idTokenSigningAlg\": \"RS256\",
				\"redirectUris\": [
					\"http://localhost:8000/auth/callback\"
				],
				\"renewRefreshTokenExpiry\": 86400,
				\"sendAllKnownUserAttributes\": \"false\"
			},
			\"token\": {
				\"accessTokenType\": \"default\",
				\"attributeMappings\": [
					{
						\"targetName\": \"may_act\",
						\"function\": {
							\"custom\": \"{\\n  \\\"sub\\\": \\\"${ACTOR_APP_CLIENT_ID}\\\"\\n}\"
						}
					}
				]
			},
			\"grantProperties\": {
				\"generateDeviceFlowQRCode\": \"false\"
			},
			\"requirePkceVerification\": \"true\",
			\"consentAction\": \"always_prompt\",
			\"applicationUrl\": \"http://localhost:8000\",
			\"scopes\": [],
			\"restrictEntitlements\": true,
			\"entitlements\": []
		},
		\"saml\": {
			\"properties\": {
				\"companyName\": \"IBM Verify MCP\"
			}
		}
	},
	\"apiAccessClients\": []
  }")

# Extract Subject application ID from response
SUBJECT_APP_ID=$(echo "$SUBJECT_APP_RESPONSE" | grep -o '"href":"/appaccess/v1.0/applications/[0-9]\+"' | sed 's/.*\/applications\///' | tr -d '"')

if [ -z "$SUBJECT_APP_ID" ]; then
    echo "Error: Failed to extract Subject application ID"
    echo "Response: $SUBJECT_APP_RESPONSE"
    exit 1
fi

echo "Subject application onboarded successfully"
echo "Subject Application ID: $SUBJECT_APP_ID"
echo ""

# Retrieve Subject application details to get client credentials
echo "Retrieving Subject application credentials..."
SUBJECT_APP_DETAILS_RESPONSE=$(curl -s --request GET \
  --url "${TENANT_URL}/v1.0/applications/${SUBJECT_APP_ID}" \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}")

# Extract client ID and client secret from response
SUBJECT_APP_CLIENT_ID=$(echo "$SUBJECT_APP_DETAILS_RESPONSE" | grep -o '"clientId":"[^"]*"' | head -1 | cut -d'"' -f4)
SUBJECT_APP_CLIENT_SECRET=$(echo "$SUBJECT_APP_DETAILS_RESPONSE" | grep -o '"clientSecret":"[^"]*"' | head -1 | cut -d'"' -f4)

if [ -z "$SUBJECT_APP_CLIENT_ID" ] || [ -z "$SUBJECT_APP_CLIENT_SECRET" ]; then
    echo "Error: Failed to extract Subject application client credentials"
    echo "Response: $SUBJECT_APP_DETAILS_RESPONSE"
    exit 1
fi

echo "Subject application credentials retrieved successfully"
echo "Subject Application Client ID: $SUBJECT_APP_CLIENT_ID"
echo "Subject Application Client Secret: $SUBJECT_APP_CLIENT_SECRET"
echo ""

# Create STS client
echo "Creating STS client..."
STS_RESPONSE=$(curl -s -i --request POST \
  --url "${TENANT_URL}/oidc-mgmt/v1.0/sts/oauth/clients" \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{
        "clientId": "",
        "clientName": "IBM Verify MCP Server STS Client",
        "enabled": true,
        "tokenExchangeSettings": {
            "subjectTokenTypes": [
                "urn:ietf:params:oauth:token-type:access_token"
            ],
            "actorTokenTypes": [
                "urn:ietf:params:oauth:token-type:access_token"
            ],
            "requestedTokenTypes": [
                "urn:ietf:params:oauth:token-type:access_token"
            ],
            "actorTokenRequired": true
        },
        "clientAuthentication": {
            "clientAuthMethod": "default",
            "clientSecret": null,
            "clientAssertionSigningAlg": "RS256",
            "validateClientAssertionJti": true,
            "allowedClientAssertionVerificationKeys": [],
            "tlsClientAuthAttribute": "subject_dn",
            "tlsClientAuthAttributeValue": ""
        },
        "tokenSettings": {
            "signingAlg": "RS256",
            "signingKeyLabel": "",
            "encryptAlg": "none",
            "encryptEnc": "none",
            "encryptKey": "",
            "jwksUri": "",
            "attributeMap": [],
            "accessTokenLifetime": 3600,
            "accessTokenType": "jwt",
            "introspectMap": [],
            "certificateBoundAccessTokens": false,
            "dpopBoundAccessTokens": false,
            "validateDPoPProofJti": false,
            "dpopProofSigningAlg": "RS256",
            "restrictEntitlements": true,
            "entitlements": [
                "manageAccessRequest",
				"readAccessRequest",
                "manageAccessRequestActivities",
				"readAccessAsManager",
	            "manageAccessAsManager",
                "manageAppAccessOwner",
				"manageAppAccessAdmin",
                "manageEntitlements",
                "readAppConfig",
				"readAttributes",
	            "manageAttributes",
				"readAttributesForDisplay",
				"readUsers",
	            "readGroups",
            	"readStandardGroups",
            	"readGroupMembers",
            	"readStandardGroupMembers",
                "readUserGroups",
            	"readUsersGroupMembership",
            	"readUsersStandardGroupMembership",
	            "manageUsers",
            	"manageUsersInStandardGroups",   
            	"manageUserGroups",
            	"manageAllUserGroups",
            	"manageUserStandardGroups",
			    "manageGroups",
            	"manageStandardGroups",
            	"manageGroupMembers",
            	"manageStandardGroupMembers",
			    "readMFAMethods",
			    "manageMFAMethods",
	            "manageEnrollMFAMethodAnyUser",
                "readEnrollMFAMethodAnyUser",
                "manageEnrollMFAMethod",
                "readEnrollMFAMethod"
            ],
            "restrictScopes": false,
            "scopes": [],
            "exchangeForSSOSessionOption": "default",
            "tctxMapping": "",
            "restrictAuthDetailTypes": true,
            "ignoreUnknownAuthDetailTypes": true,
            "authDetailTypes": []
        },
        "clientGroups": {
            "tokenExchange": []
        },
        "policyId": null
    }')

# Extract location header from response
STS_LOCATION=$(echo "$STS_RESPONSE" | grep -i "^location:" | sed 's/location: //i' | tr -d '\r')

if [ -z "$STS_LOCATION" ]; then
    echo "Error: Failed to extract STS client location"
    echo "Response: $STS_RESPONSE"
    exit 1
fi

# Extract STS client ID from location URL
STS_CLIENT_ID=$(echo "$STS_LOCATION" | grep -o '[^/]*$' | tr -d '[:space:]')

if [ -z "$STS_CLIENT_ID" ]; then
    echo "Error: Failed to extract STS client ID"
    echo "Location: $STS_LOCATION"
    exit 1
fi

echo "STS client created successfully"
echo "STS Client ID: $STS_CLIENT_ID"
echo ""

# Retrieve STS client details to get client secret
echo "Retrieving STS client credentials..."
STS_DETAILS_RESPONSE=$(curl -s --request GET \
  --url "$STS_LOCATION" \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}")

# Extract client secret from response
STS_CLIENT_SECRET=$(echo "$STS_DETAILS_RESPONSE" | grep -o '"clientSecret":"[^"]*"' | head -1 | cut -d'"' -f4)

if [ -z "$STS_CLIENT_SECRET" ]; then
    echo "Error: Failed to extract STS client secret"
    echo "Response: $STS_DETAILS_RESPONSE"
    exit 1
fi

echo "STS client credentials retrieved successfully"
echo ""
echo "---------------------------"
echo "The IBM Verify MCP Server related applications and Token exchange client"
echo "have been successfully setup on your tenant."
echo ""
echo "Use the following script to setup the environment variables needed for"
echo "your MCP Server"
echo ""
echo "NOTE: Review 'setup-env.sh.example' script to customize other settings"
echo ""
echo "setup-env.sh"
echo ""
echo '```'
echo "#!/bin/bash"
echo "export IBM_VERIFY_TENANT_URL=\"${TENANT_URL}\""
echo "export IBM_VERIFY_CLIENT_ID=\"${SUBJECT_APP_CLIENT_ID}\""
echo "export IBM_VERIFY_CLIENT_SECRET=\"${SUBJECT_APP_CLIENT_SECRET}\""
echo ""
echo "export IBM_VERIFY_STS_CLIENT_ID=\"${STS_CLIENT_ID}\""
echo "export IBM_VERIFY_STS_CLIENT_SECRET=\"${STS_CLIENT_SECRET}\""
echo ""
echo "export IBM_VERIFY_ACTOR_CLIENT_ID=\"${ACTOR_APP_CLIENT_ID}\""
echo "export IBM_VERIFY_ACTOR_CLIENT_SECRET=\"${ACTOR_APP_CLIENT_SECRET}\""
echo ""
echo "export AUTHENTICATION_METHOD=\"oidc_proxy\""
echo "export IBM_VERIFY_BASE_URL=\"http://localhost:8000\""
echo "export MCP_TRANSPORT=\"streamable-http\""
echo '```'
echo ""
echo "You can setup the environment by using the following command:"
echo ""
echo "source setup-env.sh"
echo ""
echo "---------------------------"
echo ""
echo "IMPORTANT - Next Steps:"
echo "  Before using the MCP Server, you must entitle users to the 'MCP Server Subject' application."
echo "  To do this:"
echo "    1. Go to Admin Console"
echo "    2. Navigate to: Applications -> MCP Server Subject"
echo "    3. Go to the Entitlement tab"
echo "    4. Add the required users or groups"
echo ""
echo "---------------------------"
EOF

# Make the script executable
chmod +x setup-verify-tenant.sh

The script is now ready to run.

Step 5: Run Automated Setup Script

5.1 Execute the Script

./setup-verify-tenant.sh

5.2 Provide Required Information

The script prompts you for:

  1. IBM Verify tenant URL

    • Example: https://your-tenant.verify.ibm.com
    • You can enter with or without https://

  2. API Client ID

    • The Client ID from Step 2.4

  3. API Client Secret

    • The Client Secret from Step 2.4
    • Input is hidden for security

5.3 What the Script Creates

The script automatically creates three components:

ComponentTypePurpose
MCP Server ActorOAuth ApplicationProvides actor token for token exchange
MCP Server SubjectOAuth ApplicationHandles user authentication with PKCE
MCP Server STSToken Exchange ClientPerforms OAuth 2.0 token exchange

Configuration Details:

  • Actor application uses client credentials grant
  • Subject application uses authorization code + PKCE grant
  • Subject application redirect URI: http://localhost:8000/auth/callback
  • STS client has restricted entitlements for security
  • All tokens expire after 3600 seconds (1 hour)

5.4 Save Generated Credentials

Upon successful completion, the script outputs a setup-env.sh file with all credentials:

#!/bin/bash
export IBM_VERIFY_TENANT_URL="https://your-tenant.verify.ibm.com"

export IBM_VERIFY_CLIENT_ID="subject-client-id"
export IBM_VERIFY_CLIENT_SECRET="subject-client-secret"

export IBM_VERIFY_STS_CLIENT_ID="sts-client-id"
export IBM_VERIFY_STS_CLIENT_SECRET="sts-client-secret"

export IBM_VERIFY_ACTOR_CLIENT_ID="actor-client-id"
export IBM_VERIFY_ACTOR_CLIENT_SECRET="actor-client-secret"

export IBM_VERIFY_ACTOR_CLIENT_SECRET="actor-client-secret"
export IBM_VERIFY_ACTOR_CLIENT_SECRET="actor-client-secret"

export IBM_VERIFY_BASE_URL="http://localhost:8000"

export MCP_TRANSPORT="streamable-http"

Save this file securely - you need it to run the MCP Server.

Step 6: Entitle users to MCP Server

⚠ CRITICAL STEP - Without this, users cannot authenticate!

6.1 Navigate to application

  1. Go to IBM Verify Admin Console
  2. Navigate to Applications
  3. Find and click MCP Server Subject

6.2 Add user entitlements

  1. Click the Entitlement tab
  2. Click Add entitlement
  3. Select users or groups who should access the MCP Server
  4. Click Save

Who to entitle:

  • Individual users who use the MCP Server
  • Groups containing MCP server users
  • Entitle yourself for testing

Step 7: Verify Setup

Before proceeding to MCP Server installation:

7.1 Checklist

  • API client created with both required entitlements
  • Setup script executed successfully
  • setup-env.sh file saved securely
  • Users entitled to "MCP Server Subject" application
  • All credentials documented and stored safely

7.2 Test Configuration (Optional)

You can verify the setup by testing token acquisition:

# Source the environment file
source setup-env.sh

# Test actor token
curl -X POST "${IBM_VERIFY_TENANT_URL}/v1.0/endpoint/default/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=${IBM_VERIFY_ACTOR_CLIENT_ID}" \
  -d "client_secret=${IBM_VERIFY_ACTOR_CLIENT_SECRET}"

Expected response: JSON with access_token field.

Troubleshooting

IssueCauseSolution
Failed to obtain access tokenInvalid credentials or missing entitlementsVerify API client ID or secret and check both entitlements are assigned
Failed to create applicationMissing manageAppAccessAdmin (Manage application lifecycle)Add manageAppAccessAdmin (Manage application lifecycle) entitlement to API client
Failed to create STS clientMissing manageSTSClients (Manage STS clients and token types)Add manageSTSClients (Manage STS clients and token types) entitlement to API client
Network connection errorFirewall or proxy blockingCheck network connectivity to tenant URL
Script permission deniedFile not executableRun chmod +x setup-verify-tenant.sh

Next Steps

After completing this setup:

  1. ✅ Save the setup-env.sh file in a secure location
  2. ✅ Entitle users to "MCP Server Subject" application
  3. ✅ Proceed to MCP Server installation following the main installation guide
  4. ✅ Source environment variables before running MCP Server: source setup-env.sh

Proceed to the MCP Server Installation Guide

Need help? For further details, consult IBM Verify Documentation or contact your administrator.

Updated about 2 hours ago

Did this page help you?