MCP Gateway

The available MCP Port Types are:

To configure MCP Services in an Application:

1. Go to Applications > Application List.

2. Open the application that hosts the MCP server.

3. Click the Hosts And Services tab.

4. Locate the host and click Add Service, or select an existing service to edit.

5. Select the MCP or MCPS service.

6. Provide the port number the MCP server listens.

   The default ports are 80 for MCP, 443 for MCPS.

7. Provide a Description and a Custom URI if the MCP server is mounted at a non-root path.

8. Click Save.

After saving, the service appears in the tool catalog and is accessible to AI Agents that have permission to access this application.

Read Create an AI Agent for information on AI Agent's access to applications

• Consent Initiation: The user initiates a connection to an external MCP within the UI.

• Authorization: The user is redirected to the external service’s OAuth provider.

• User Authentication: The user authenticates with the external service.

• Scope Approval: The user reviews and approves the scopes requested by the system.

• Token Exchange: The system exchanges the authorization code for an access token.

• Token Storage: The access token is encrypted and stored, associated with the user’s account.

• MCP Access: When the MCP needs to access the external service, the system uses the stored token.

The standard flow is the recommended approach for most deployments. The external OAuth provider must be configured to accept the default callback URL.

Configuration Requirements

For the external MCP to support user-delegated OAuth, configure:

• OAuth Provider URL: The authorization server’s endpoint for the external service.

• Token Endpoint: The server’s token exchange endpoint.

• Client ID & Secret: Credentials for the PAS system as an OAuth client.

• Default Redirect URI: The PAS system provides this automatically based on your deployment.

User Workflow

1. Navigate to User Profile > MCP Connections.

2. Locate the external MCP you want to connect.

3. Click Connect.

   You are redirected to the external service’s login page.

4. Authenticate with your credentials for the external service.

5. Review the scopes the PAS system is requesting.

6. Click Approve.

You are redirected back to the server with an authorization confirmation.

Some deployments require manual configuration of callback URLs when:

• Your PAS system is behind a proxy or load balancer with custom URLs.

• Your OAuth provider has strict URL validation requirements.

• You need to support multiple callback URLs for failover.

Configuration Requirements

Instead of using the default callback URL, manually specify:

• Callback URL(s): One or more fully-qualified URIs that the OAuth provider will redirect to after user authentication.

• State Parameter Validation: Ensure your callback URL preservation of state token across redirects.

• Custom Port or Path: If your PAS system uses a non-standard port or path, register this with the OAuth provider.

Manually Configuring Callback URLs

1. Contact your OAuth provider to add custom callback URL(s).

2. Register all required URLs in your OAuth provider’s configuration.

3. In the PAS server, configure the external MCP to use these custom URLs.

After a user authorizes an external MCP, the system manages the token lifecycle automatically:

• Token Storage: Tokens are encrypted at rest and stored in the secure token vault.

• Token Refresh: If the external service provides a refresh token, it is automatically used to obtain new access tokens before expiration.

• Token Expiration: Expired tokens are automatically refreshed. If refresh fails, the user must re-authorize.

• Revocation: Users can revoke stored tokens at any time, immediately preventing the system from accessing the external service on their behalf.

Your PAS server supports multiple authentication header configurations:

Bearer Token (Standard)

Header Format:

Authorization: Bearer <token>

Example Configuration:

• Header Name: Authorization

• Header Prefix: Bearer

• Token Value: <token_value>

Result Header:

Authorization: Bearer <token_value>

API Key Header

Header Format:

X-API-Key: <token>

Example Configuration:

• Header Name: X-API-Key

• Header Prefix: (none)

• Token Value: <token_value>

Result Header:

X-API-Key: <token_value>

Custom Authorization Header

Header Format:

<CustomHeaderName>: <Prefix> <token>

Multiple Headers

Some MCPs require both an API key and a session token:

Authorization: Bearer <token>

X-Session-ID: <session>

Configuration in the Server

• Token 1: Header Authorization, Prefix Bearer, Value: personal token

• Token 2: Header X-Session-ID, Prefix: (none), Value: session identifier

To use personal access tokens with an external MCP:

1. Generate a personal access token in the external service.

2. In your server, navigate to MCP Connections.

3. Select the MCP and choose Authenticate with Personal Access Token.

4. Select the authentication method.

5. Enter the header name and header prefix.

6. Paste your personal access token.

7. Click Save.

Personal access tokens are managed differently than OAuth tokens:

• Expiration: PATs typically do not expire, but check your external service’s policy.

• Refresh: PATs are static and do not refresh. If a token expires, generate a new one in the external service and update the PAS server.

• Revocation: Users can revoke PAT credentials from the PAS server at any time, immediately preventing token use.

• Rotation: Periodically rotate PATs by generating new tokens in the external service and updating the PAS server.

To revoke access to an MCP:

1. Locate the MCP in Profile > Connected Services list.

2. Click Revoke.

3. Confirm the revocation in the dialog.

The connection is immediately terminated and the VPAM server can no longer access the external service on your behalf.

Effect of Revocation:

The stored OAuth token or PAT is deleted from the system. Any pending operations using the token are canceled.

To reconnect, you must re-authorize the MCP.

If an MCP connection expires, fails, or you want to re-authorize after revoking consents:

1. Navigate to Profile > Connected Services.

2. Locate the MCP with status Connection Expired or Authorization Required.

3. Click Re-authorize.

Complete the OAuth or PAT authentication process.

To view details about a specific MCP authorization:

1. Navigate to Profile > Connected Services.

2. Click the MCP name or an info icon.

3. View the Authorization Details.

System Administrators configure namespaces during MCP setup:

1. Navigate to MCP Configuration.

2. When adding or editing an MCP service, assign it to one or more namespaces.

3. Save the configuration.

POST https://<server>/mcp

To scope requests to a single site, append the site name as a path segment:

POST https://<server>/mcp/{site-name}

URL-encode site names that contain spaces or special characters. For example, My Site becomes My%20Site.

Include a bearer token in every request:

Authorization: Bearer <access_token>

The gateway assigns a session ID on the first successful initialize request and returns it in the Mcp-Session-Id response header. Include this header in all subsequent requests:

Mcp-Session-Id: <uuid>

If the header is omitted on a non-initialize request, the gateway returns an error.

Requests use JSON-RPC 2.0:

{

"jsonrpc": "2.0",

"id": 1,

"method": "tools/list"

}

The response format is determined by the Accept request header:

Before calling any other method, the AI Agent must complete the two-step initialization handshake:

1. Send initialize: The gateway creates a session, returns its capabilities, and sets the Mcp-Session-Id header.

   // Step 1 — initialize

   POST /mcp

   Authorization: Bearer <token>

   Content-Type: application/json

   {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}

   // Response includes:

   // Mcp-Session-Id: <uuid>

2. Send notifications/initialized: The agent acknowledges the handshake. Include the Mcp-Session-Id received in step 1.

   // Step 2 — initialized (use the session ID from the response above)

   POST /mcp

   Authorization: Bearer <token>

   Mcp-Session-Id: <uuid>

   Content-Type: application/json

   {"jsonrpc":"2.0","method":"notifications/initialized"}

The initialize response body declares the gateway's supported capabilities:

{

"jsonrpc": "2.0",

"id": 1,

"result": {

"protocolVersion": "2025-06-18",

"serverInfo": { "name": "Privileged Access MCP Gateway", "version": "<version>" },

"capabilities": {

"tools": { "listChanged": true },

"prompts": { "listChanged": true },

"resources": { "subscribe": false, "listChanged": true }

}

}

}

The notification stream (GET /mcp) pushes server-sent events to the AI Agent:

• Keepalive comments are sent every 15 seconds to prevent proxy timeouts.

• notifications/tools/list_changed is sent whenever the tool catalog changes (for example, when a new MCP service is added or removed).

• The stream times out after 30 minutes of inactivity and must be reopened.

Example SSE stream:

: keepalive

data: {"jsonrpc":"2.0","method":"notifications/tools/list_changed"}

MCP Gateway sessions expire after 15 minutes with no POST or DELETE requests. When a session expires:

• The session is automatically removed from the registry.

• All associated audit accesses are automatically closed.

• Subsequent requests using the expired session ID receive an error; the agent must start a new session with initialize.

To end a session explicitly before it times out, send a DELETE /mcp request with the Mcp-Session-Id header.