IBM Verify MCP Server - Configuring MCP Clients

Overview

This guide covers how to configure MCP clients (Claude Desktop and IBM Bob) to connect to your IBM Verify MCP Server. After configuration, you can use natural language to interact with IBM Verify through the MCP protocol.

Prerequisites

Before configuring MCP clients, ensure you have:

✅ Completed Tenant Setup
✅ Able to access Verify tenant
✅ Completed MCP Server Installation
✅ MCP Server running and accessible
✅ MCP Server URL (e.g., https://verify-mcp-server.example.com or http://localhost:8000)
✅ uv installed on the client machine — install it for your OS from the uv installation guide. uvx, which is used to run fastmcp-remote, is included with uv.

Windows users — one-time setup required: Some MCP hosts on Windows require fastmcp-remote to be pre-fetched before it can be invoked through uvx. Run the following command in a terminal before configuring your MCP client:

uvx [email protected] --help

This downloads and caches the package. You only need to do this once.

Authentication Modes

The IBM Verify MCP Server supports two authentication modes. Choose the one that best fits your use case.

Mode 1: OAuth 2.0 Authorization Code Flow (Default)

This is the primary and recommended authentication method. When an unauthenticated client connects, the MCP server responds with HTTP 401 Unauthorized, which triggers a browser-based authentication flow. The user signs in to IBM Verify through their browser, and after authentication completes, the client can invoke MCP tools.

Best for: Human users connecting interactively through Claude Desktop or IBM Bob.

Mode 2: Direct Access Token Authentication

Clients can supply a valid IBM Verify access token directly in the MCP client configuration through the Authorization request header. Because the token is provided upfront, no browser-based authentication flow is required — the client connects immediately.

Best for: AI agents, automated pipelines, or applications that have already authenticated through a separate mechanism.

Note: Access tokens are sensitive credentials and must be handled carefully.

Persona

The persona request header controls which set of tools the MCP server exposes to the connected client.

Persona value	Intended for	Tools exposed
`end_user`	Regular users — employees, contractors	Self-service tools: access requests, MFA self-management, password reset
`admin`	IT administrators, help desk, security teams	Administrative tools: user/group/application management, tenant-wide MFA, directory attributes

If the persona header is omitted, the server defaults to end_user.

Why personas are separate:

Each persona exposes only the tools relevant to that audience. This is a deliberate design choice — loading only the tools a user actually needs keeps the AI model's context lean and reduces unnecessary token usage. Admin users do not see end-user tools, and end users do not see admin tools.

What happens if a user connects with the wrong persona?

The MCP server enforces entitlements at the token level, not just at the persona level. If an end user connects with the admin persona and attempts to invoke an administrative tool, the IBM Verify API returns a 403 Forbidden response. No privileged operation can be performed without the correct entitlements on the token — the persona controls what tools are surfaced, while IBM Verify controls what operations are actually permitted.

For a full breakdown of which tools belong to each persona, see Using MCP Tools.

About `fastmcp-remote`

fastmcp-remote is a lightweight bridge that connects MCP hosts (like Claude Desktop or IBM Bob) to remote MCP servers hosted over HTTP. MCP hosts expect to launch a local command — fastmcp-remote satisfies that expectation while transparently proxying all requests to the remote server URL provided. It handles OAuth automatically on first connect, opening a browser sign-in flow when the server requires authentication, and stores tokens locally for subsequent runs.

See the fastmcp-remote documentation for details.

MCP Client Configuration Reference

All supported MCP clients use the same JSON configuration structure. Configure your preferred auth mode and persona here, then follow the provided client-specific steps to apply it.

MCP Server URL by Deployment Environment

The server URL to use in all the following configuration examples depends on where your MCP Server is deployed:

Environment	URL
Local development	`http://localhost:8000/mcp`
VM / Fyre (behind nginx)	`https://<host>/mcp`
Kubernetes	`https://<verify-mcp-server-service>/mcp`

The /mcp path suffix is required in all cases. Replace the placeholder values (<host>, <verify-mcp-server-service>) with your actual hostname or Kubernetes service name.

VM / Fyre Deployments — nginx Reverse Proxy

When deploying on a VM or Fyre system, nginx must be configured as an HTTPS reverse proxy in front of the MCP Server (which runs on port 8000 over plain HTTP). For setup instructions, See NGINX Reverse Proxy or the How To Configure Nginx as a Reverse Proxy on Ubuntu.

OAuth Authentication (Default) — End User

{
  "mcpServers": {
    "ibm-verify": {
      "command": "uvx",
      "args": [
        "[email protected]",
        "http://localhost:8000/mcp",
        "--header",
        "persona: end_user"
      ]
    }
  }
}

OAuth Authentication — Admin

{
  "mcpServers": {
    "ibm-verify": {
      "command": "uvx",
      "args": [
        "[email protected]",
        "http://localhost:8000/mcp",
        "--header",
        "persona: admin"
      ]
    }
  }
}

Direct Token Authentication — End User

{
  "mcpServers": {
    "ibm-verify": {
      "command": "uvx",
      "args": [
        "[email protected]",
        "http://localhost:8000/mcp",
        "--header",
        "persona: end_user",
        "--header",
        "Authorization: Bearer <your-access-token>"
      ]
    }
  }
}

Replace <your-access-token> with a valid IBM Verify access token. The token must correspond to a user entitled to use the MCP server.

Direct Token Authentication — Admin

{
  "mcpServers": {
    "ibm-verify": {
      "command": "uvx",
      "args": [
        "[email protected]",
        "http://localhost:8000/mcp",
        "--header",
        "persona: admin",
        "--header",
        "Authorization: Bearer <your-access-token>"
      ]
    }
  }
}

Replace http://localhost:8000/mcp with your production server URL (e.g., https://verify-mcp-server.example.com/mcp) when deploying outside of local development. The /mcp path suffix is required.

Self-Signed Certificates (VM / Fyre with nginx)

Lab and Fyre environments commonly use self-signed TLS certificates. By default, fastmcp-remote rejects connections to servers with untrusted certificates. To allow the client to connect, add an env block to your configuration pointing to the certificate file on your machine:

{
  "mcpServers": {
    "ibm-verify": {
      "command": "uvx",
      "args": [
        "[email protected]",
        "https://<host>/mcp",
        "--header",
        "persona: end_user"
      ],
      "env": {
        "UV_NATIVE_TLS": "1",
        "SSL_CERT_FILE": "/path/to/nginx-selfsigned.crt",
        "REQUESTS_CA_BUNDLE": "/path/to/nginx-selfsigned.crt"
      }
    }
  }
}

Replace /path/to/nginx-selfsigned.crt with the absolute path to the certificate file on your machine. The UV_NATIVE_TLS flag instructs uv to use the system's native TLS stack, while SSL_CERT_FILE and REQUESTS_CA_BUNDLE ensure the certificate is trusted by the underlying HTTP libraries.

This env block is only needed when connecting to a server with a self-signed certificate. Standard deployments with a CA-signed certificate do not require it.

Fallback: Installing `fastmcp-remote` Globally

In some environments uvx fastmcp-remote may not work reliably (for example, certain Windows setups or restricted PATH configurations). As a fallback, install fastmcp-remote once as a global tool:

uv tool install fastmcp-remote

Then update your configuration to invoke it directly — use "command": "fastmcp-remote" and remove "[email protected]" from args:

{
  "mcpServers": {
    "ibm-verify": {
      "command": "fastmcp-remote",
      "args": [
        "https://<host>/mcp",
        "--header",
        "persona: end_user"
      ],
      "env": {
        "UV_NATIVE_TLS": "1",
        "SSL_CERT_FILE": "/path/to/nginx-selfsigned.crt",
        "REQUESTS_CA_BUNDLE": "/path/to/nginx-selfsigned.crt"
      }
    }
  }
}

The preceding env block applies to self-signed certificate setups. Omit it entirely if your server uses a CA-signed certificate.

Configuration Parameters

Parameter	Description	Required
`command`	The command used to launch the MCP client bridge.	Yes
`[email protected]`	The `fastmcp-remote` package pinned to version 3.4.3 (tested and verified to work with this server), fetched through `uvx`.	Yes
Server URL	Full URL to the MCP endpoint, ending in `/mcp`.	Yes
`--header "persona: ..."`	Selects the tool set exposed to the client. Values: `end_user` or `admin`. Defaults to `end_user` if omitted.	No
`--header "Authorization: Bearer ..."`	Provides an access token directly; skips the OAuth browser flow.	Only for Direct Token mode
`--debug`	Enables verbose logging. Remove in production.	No

Option 1: Configuring Claude Desktop

Claude Desktop is Anthropic's desktop application that supports the Model Context Protocol.

1.1 Prerequisites

Claude Desktop installed (download from claude.ai)
A valid Claude account with the necessary access to sign in to Claude Desktop
MCP Server URL accessible from your machine

1.2 Locate the Configuration File

Claude Desktop stores MCP server configurations in a JSON file:

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

1.3 Apply the Configuration

Open the configuration file:

# macOS/Linux
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows
notepad %APPDATA%\Claude\claude_desktop_config.json

Paste in the configuration snippet for your chosen authentication mode and persona from the MCP Client Configuration Reference section.

1.4 Restart Claude Desktop

After saving the configuration:

Quit Claude Desktop completely
- macOS: Cmd + Q
- Windows: Right-click system tray icon → Exit
- Linux: Close all windows
Restart Claude Desktop
Verify the connection — see Validating the Connection.

On first launch with OAuth mode, Claude Desktop opens your browser to the IBM Verify sign-in page. Sign in with your IBM Verify credentials. After successful sign-in, the browser redirects back and the client proceeds automatically.

1.5 Troubleshooting Claude Desktop

Issue: MCP server not appearing

Validate JSON syntax at jsonlint.com
Confirm the file is saved in the correct location
Restart Claude Desktop completely
Check Claude Desktop logs:
- macOS: ~/Library/Logs/Claude/
- Windows: %APPDATA%\Claude\logs\

Issue: Connection timeout

Verify the MCP Server URL is reachable: curl https://verify-mcp-server.example.com/health
Check firewall settings
Verify SSL certificate if using HTTPS

Option 2: Configuring IBM Bob

IBM Bob is IBM's AI assistant that supports MCP servers by using the same JSON configuration format as Claude Desktop.

2.1 Prerequisites

IBM Bob IDE extension installed
Bob version with MCP support
MCP Server URL accessible from your machine

2.2 Configuration Scope

IBM Bob supports two configuration scopes:

Method A: Global Configuration (Recommended)

Applies to all projects on your machine.

macOS / Linux:

~/.bob/settings/mcp.json

Windows:

%USERPROFILE%\.bob\settings\mcp.json

Method B: Project-Specific Configuration

Applies only to a single project. Place the file in your project root:

macOS / Linux:

.bob/mcp.json

Windows:

.bob\mcp.json

Both methods use the same JSON format. Paste in the configuration snippet for your chosen authentication mode and persona from the MCP Client Configuration Reference section.

2.3 Reload Bob Configuration

After saving the configuration, reload IBM Bob to apply the new MCP server settings.

2.4 Troubleshooting IBM Bob

Issue: MCP server not loading

Validate JSON syntax
Confirm the file path is correct
Reload Bob configuration
Check Bob logs in the IDE console

Issue: Connection errors

Test the server URL: curl https://verify-mcp-server.example.com/health
Check network connectivity and SSL certificates
Confirm your Bob version supports MCP

3. Validating the Connection

After configuring your MCP client, validate the connection is working.

3.1 Check Server Health

curl https://verify-mcp-server.example.com/health
# Expected: {"status":"healthy","service":"IBM Verify MCP Server"}

3.2 Validate in Claude Desktop

Open Claude Desktop and start a new conversation
Look for the MCP indicator — it should show ibm-verify (or your configured server name)
Test tool discovery:
```
Can you list the available tools from IBM Verify?
```
The tools shown should match your configured persona.
Test a tool execution:
```
How many users are there in my tenant?
```
Claude should invoke ibm_verify_get_user_count and display the count. (Admin persona required for this tool.)

3.3 Validate in IBM Bob

Open the Bob chat panel in your IDE
Confirm "IBM Verify" appears in the MCP servers list with a connected status
Test tool discovery:
```
List all available IBM Verify tools
```
Test a tool execution:
```
How many users are there in my tenant?
```

3.4 Validation Checklist

MCP Server health endpoint responds
MCP client shows server as connected
Tools listed match the configured persona (end_user or admin)
Can execute a simple tool successfully
No authentication errors in logs

3.5 Common Validation Issues

"Server not found" or "Connection refused"

Confirm the MCP Server URL is correct and reachable

Check the server is running:

# Kubernetes
kubectl get pods -n verify-mcp-server

# Docker
docker ps | grep verify-mcp-server

Check firewall rules

"Authentication failed"

Confirm tenant setup is complete and the user is entitled to the MCP Server application.
Check credentials in server configuration.
If using Direct Token mode, confirm the token has not expired.
Review server logs for specific auth error codes.

"Unexpected or missing tools"

Confirm the persona header value is exactly end_user or admin (case-sensitive)
Restart or reload the MCP client
Verify the authenticated user holds the entitlements expected for the configured persona

4. Security Best Practices

Network Security

✅ Always use HTTPS in production
✅ Validate SSL certificates
✅ Use a VPN for remote access
✅ Implement IP allowlisting where possible
✅ Use firewall rules to restrict access

Configuration Security

✅ Never commit configuration files containing access tokens to source control
✅ Use environment variables for sensitive data

✅ Restrict file permissions on configuration files:

chmod 600 ~/.bob/mcp-servers.json
chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json

✅ Rotate tokens regularly
✅ Use different configurations for development and production environments

Access Control

✅ Ensure each user is entitled to the correct MCP application in IBM Verify
✅ Monitor for suspicious activity
✅ Follow principle of least privilege
✅ Implement session timeouts
✅ Assign the end_user persona to regular users; reserve admin for administrators
✅ Audit MCP tool usage through IBM Verify audit logs
✅ Revoke tokens promptly when a user's access should be removed

5. Troubleshooting

For issues not covered here, refer to the comprehensive Troubleshooting Guide, which covers:

Connection Issues — server connectivity, DNS, SSL certificates
Authentication Issues — OAuth errors, tenant setup, user entitlements, expired tokens
Configuration Issues — JSON validation, file permissions, client logs
MCP Client-Specific Issues - Claude Desktop and IBM Bob troubleshooting

Quick debug commands:

# Test server health
curl -v https://verify-mcp-server.example.com/health

# Validate JSON configuration
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python -m json.tool

# Stream server logs (Kubernetes)
kubectl logs -f -n verify-mcp-server -l app=verify-mcp-server

# Stream server logs (Docker)
docker logs -f verify-mcp-server

6. Next Steps

Now that your MCP client is configured and validated:

👉 Using IBM Verify MCP Tools — Explore all available tools with examples and use cases.

What you will learn:

Full list of tools, organized by persona
Natural language examples for each tool category
Common end-to-end workflows

Additional Resources

Configuration Complete! You're now ready to use IBM Verify MCP Tools with your configured client.

IBM Verify MCP Server - Configuring MCP Clients

Overview

Prerequisites

Authentication Modes

Mode 1: OAuth 2.0 Authorization Code Flow (Default)

Mode 2: Direct Access Token Authentication

Persona

About fastmcp-remote

MCP Client Configuration Reference

MCP Server URL by Deployment Environment

VM / Fyre Deployments — nginx Reverse Proxy

OAuth Authentication (Default) — End User

OAuth Authentication — Admin

Direct Token Authentication — End User

Direct Token Authentication — Admin

Self-Signed Certificates (VM / Fyre with nginx)

Fallback: Installing fastmcp-remote Globally

Configuration Parameters

Supported MCP Clients

Option 1: Configuring Claude Desktop

1.1 Prerequisites

1.2 Locate the Configuration File

1.3 Apply the Configuration

1.4 Restart Claude Desktop

1.5 Troubleshooting Claude Desktop

Option 2: Configuring IBM Bob

2.1 Prerequisites

2.2 Configuration Scope

Method A: Global Configuration (Recommended)

Method B: Project-Specific Configuration

2.3 Reload Bob Configuration

2.4 Troubleshooting IBM Bob

3. Validating the Connection

3.1 Check Server Health

3.2 Validate in Claude Desktop

3.3 Validate in IBM Bob

3.4 Validation Checklist

3.5 Common Validation Issues

4. Security Best Practices

Network Security

Configuration Security

Access Control

5. Troubleshooting

6. Next Steps

Additional Resources

About `fastmcp-remote`

Fallback: Installing `fastmcp-remote` Globally