Storing Connection Tokens

POST /v1/mgmt/outbound/app/connect
Authorization: Bearer <PROJECT_ID>:<MCP_ACCESS_TOKEN>
Content-Type: application/json

{
  "appId": "google-contacts",
  "options": {
    "redirectUrl": "https://your-app.com/connection-complete"
  }
}

{
  "url": "https://api.descope.com/v1/outbound/oauth/connect?appId=google-contacts&..."
}

// Request a connection URL
const response = await fetch('https://api.descope.com/v1/mgmt/outbound/app/connect', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${PROJECT_ID}:${MCP_ACCESS_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    appId: 'google-contacts',
    options: {
      redirectUrl: 'https://your-app.com/connection-complete'
    }
  })
});

const { url } = await response.json();
// Return this URL to the MCP client

import requests

# Request a connection URL
response = requests.post(
    'https://api.descope.com/v1/mgmt/outbound/app/connect',
    headers={
        'Authorization': f'Bearer {PROJECT_ID}:{MCP_ACCESS_TOKEN}',
        'Content-Type': 'application/json'
    },
    json={
        'appId': 'google-contacts',
        'options': {
            'redirectUrl': 'https://your-app.com/connection-complete'
        }
    }
)

connection_url = response.json().get('url')
# Return this URL to the MCP client

import (
    "bytes"
    "encoding/json"
    "net/http"
)

// Request a connection URL
requestBody := map[string]interface{}{
    "appId": "google-contacts",
    "options": map[string]interface{}{
        "redirectUrl": "https://your-app.com/connection-complete",
    },
}

jsonData, _ := json.Marshal(requestBody)
req, _ := http.NewRequest("POST", "https://api.descope.com/v1/mgmt/outbound/app/connect", bytes.NewBuffer(jsonData))
req.Header.Set("Authorization", fmt.Sprintf("Bearer %s:%s", projectID, mcpAccessToken))
req.Header.Set("Content-Type", "application/json")

client := &http.Client{}
resp, err := client.Do(req)
// Handle response and extract connection URL

from descope import DescopeClient
import requests

descope_client = DescopeClient(project_id="YOUR_PROJECT_ID")

def handle_mcp_tool(user_id, tool_name, tool_params):
    """
    Handle an MCP tool request with Adaptive Connect fallback.
    """
    # Step 1: Attempt to fetch the connection token
    try:
        token_response = descope_client.mgmt.outbound_application.fetch_token(
            app_id="google-contacts",
            user_id=user_id,
            options={"withRefreshToken": False}
        )
        access_token = token_response["token"]["token"]

    except Exception:
        # Step 2: Token fetch failed, request connection URL
        try:
            connect_response = requests.post(
                "https://api.descope.com/v1/mgmt/outbound/app/connect",
                headers={
                    "Authorization": f"Bearer {PROJECT_ID}:{MCP_ACCESS_TOKEN}",
                    "Content-Type": "application/json"
                },
                json={
                    "appId": "google-contacts",
                    "options": {
                        "redirectUrl": "https://your-app.com/connection-complete"
                    }
                },
                timeout=10
            )

            if connect_response.status_code == 200:
                connection_url = connect_response.json().get("url")
                # Return structured response for tool elicitation
                return {
                    "error": "connection_required",
                    "requiresConnection": True,
                    "connectionUrl": connection_url,
                    "message": (
                        f"Failed to run {tool_name}, additional permissions required. "
                        f"Please grant additional permissions using the following URL and try again: {connection_url}"
                    ),
                    "appId": "google-contacts"
                }
            return {
                "error": "connection_initiation_failed",
                "message": f"Failed to initiate connection: {connect_response.text}"
            }

        except Exception as connect_error:
            return {
                "error": "connection_request_failed",
                "message": f"Failed to request connection URL: {str(connect_error)}"
            }

    # Step 3: Token exists, execute the tool
    try:
        # Use access_token to call the third-party API
        # ... your tool logic here ...
        return {
            "success": True,
            "result": "Tool executed successfully"
        }
    except Exception as tool_error:
        return {
            "error": "tool_execution_failed",
            "message": str(tool_error)
        }

import DescopeClient from '@descope/node-sdk';

const descopeClient = DescopeClient({ projectId: 'YOUR_PROJECT_ID' });

async function handleMcpTool(
  userId: string,
  toolName: string,
  _toolParams: unknown
) {
  let accessToken: string;

  // Step 1: Attempt to fetch the connection token
  try {
    const tokenResponse =
      await descopeClient.management.outboundApplication.fetchToken(
        'google-contacts',
        userId,
        undefined,
        { withRefreshToken: false }
      );
    accessToken = tokenResponse.token.accessToken;
  } catch {
    // Step 2: Token fetch failed, request connection URL
    try {
      const connectResponse = await fetch(
        'https://api.descope.com/v1/mgmt/outbound/app/connect',
        {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${PROJECT_ID}:${MCP_ACCESS_TOKEN}`,
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            appId: 'google-contacts',
            options: {
              redirectUrl: 'https://your-app.com/connection-complete',
            },
          }),
        }
      );

      if (connectResponse.ok) {
        const { url: connectionUrl } = (await connectResponse.json()) as {
          url: string;
        };
        // Return structured response for tool elicitation
        return {
          error: 'connection_required',
          requiresConnection: true,
          connectionUrl,
          message: `Failed to run ${toolName}, additional permissions required. Please grant additional permissions using the following URL and try again: ${connectionUrl}`,
          appId: 'google-contacts',
        };
      }

      return {
        error: 'connection_initiation_failed',
        message: `Failed to initiate connection: ${await connectResponse.text()}`,
      };
    } catch (connectError) {
      return {
        error: 'connection_request_failed',
        message: `Failed to request connection URL: ${String(connectError)}`,
      };
    }
  }

  // Step 3: Token exists, execute the tool
  try {
    // Use accessToken to call the third-party API
    // ... your tool logic here ...
    return {
      success: true,
      result: 'Tool executed successfully',
    };
  } catch (toolError) {
    return {
      error: 'tool_execution_failed',
      message: String(toolError),
    };
  }
}

package main

import (
	"bytes"
	"context"
	"encoding/json"
	"fmt"
	"io"
	"net/http"

	"github.com/descope/go-sdk/descope"
	"github.com/descope/go-sdk/descope/client"
)

func handleMCPTool(ctx context.Context, descopeClient *client.DescopeClient, userID, toolName string) map[string]any {
	// Step 1: Attempt to fetch the connection token
	token, err := descopeClient.Management.OutboundApplication().FetchLatestUserToken(ctx, &descope.FetchOutboundAppUserTokenRequest{
		AppID:  "google-contacts",
		UserID: userID,
		Options: &descope.OutboundAppUserTokenOptions{
			WithRefreshToken: false,
		},
	})
	if err != nil {
		// Step 2: Token fetch failed, request connection URL
		requestBody := map[string]any{
			"appId": "google-contacts",
			"options": map[string]any{
				"redirectUrl": "https://your-app.com/connection-complete",
			},
		}
		jsonData, _ := json.Marshal(requestBody)
		req, err := http.NewRequestWithContext(ctx, http.MethodPost, "https://api.descope.com/v1/mgmt/outbound/app/connect", bytes.NewBuffer(jsonData))
		if err != nil {
			return map[string]any{
				"error":   "connection_request_failed",
				"message": fmt.Sprintf("Failed to request connection URL: %v", err),
			}
		}
		req.Header.Set("Authorization", fmt.Sprintf("Bearer %s:%s", projectID, mcpAccessToken))
		req.Header.Set("Content-Type", "application/json")

		resp, err := http.DefaultClient.Do(req)
		if err != nil {
			return map[string]any{
				"error":   "connection_request_failed",
				"message": fmt.Sprintf("Failed to request connection URL: %v", err),
			}
		}
		defer resp.Body.Close()

		body, _ := io.ReadAll(resp.Body)
		if resp.StatusCode == http.StatusOK {
			var connectResp struct {
				URL string `json:"url"`
			}
			_ = json.Unmarshal(body, &connectResp)
			// Return structured response for tool elicitation
			return map[string]any{
				"error":              "connection_required",
				"requiresConnection": true,
				"connectionUrl":      connectResp.URL,
				"message": fmt.Sprintf(
					"Failed to run %s, additional permissions required. Please grant additional permissions using the following URL and try again: %s",
					toolName, connectResp.URL,
				),
				"appId": "google-contacts",
			}
		}

		return map[string]any{
			"error":   "connection_initiation_failed",
			"message": fmt.Sprintf("Failed to initiate connection: %s", string(body)),
		}
	}

	accessToken := token.AccessToken

	// Step 3: Token exists, execute the tool
	_ = accessToken // Use accessToken to call the third-party API
	// ... your tool logic here ...
	return map[string]any{
		"success": true,
		"result":  "Tool executed successfully",
	}
}

// Delete a specific token by its ID
// Token deletion cannot be undone. Use carefully.
await descopeClient.management.outboundApplication.deleteTokenById('token-id-123');

# Delete a specific token by its ID
descope_client.mgmt.outbound_application.delete_token(
    token_id='token-id-123'
)

import com.descope.sdk.mgmt.OutboundAppsService;

outboundAppsService.deleteOutboundAppTokenById("token-id-123");

// Delete a specific token by its ID
err := descopeClient.Management.OutboundApplication().DeleteTokenByID(ctx, "token-id-123")
if err != nil {
    // Handle error
}

curl -X DELETE "https://api.descope.com/v1/mgmt/outbound/token?id=token-id-123" \
  -H "Authorization: Bearer <PROJECT_ID:MANAGEMENT_KEY>"

// Delete all tokens for a specific app and user
// Token deletion cannot be undone. Use carefully.
await descopeClient.management.outboundApplication.deleteUserTokens('my-app-id', 'user-id');

// Delete all tokens for a specific app
await descopeClient.management.outboundApplication.deleteUserTokens('my-app-id');

// Delete all tokens for a specific user
await descopeClient.management.outboundApplication.deleteUserTokens(undefined, 'user-id');

# Delete all tokens for a specific app and user
descope_client.mgmt.outbound_application.delete_user_tokens(
    app_id='my-app-id',
    user_id='user-id'
)

# Delete all tokens for a specific app
descope_client.mgmt.outbound_application.delete_user_tokens(
    app_id='my-app-id'
)

# Delete all tokens for a specific user
descope_client.mgmt.outbound_application.delete_user_tokens(
    user_id='user-id'
)

import com.descope.sdk.mgmt.OutboundAppsService;

// Delete all tokens for a specific app and user
DeleteOutboundAppUserTokensRequest deleteRequest = new DeleteOutboundAppUserTokensRequest();
deleteRequest.setAppId("google-contacts");
deleteRequest.setUserId("user-123");

outboundAppsService.deleteOutboundAppUserTokens(deleteRequest);

// Delete all tokens for a specific app and user
err := descopeClient.Management.OutboundApplication().DeleteUserTokens(ctx, "my-app-id", "user-id")
if err != nil {
    // Handle error
}

// Delete all tokens for a specific app
err = descopeClient.Management.OutboundApplication().DeleteUserTokens(ctx, "my-app-id", "")
if err != nil {
    // Handle error
}

// Delete all tokens for a specific user
err = descopeClient.Management.OutboundApplication().DeleteUserTokens(ctx, "", "user-id")
if err != nil {
    // Handle error
}

# Delete all tokens for a specific app and user
curl -X DELETE "https://api.descope.com/v1/mgmt/outbound/app/user/tokens?appId=google-contacts&userId=user-123" \
  -H "Authorization: Bearer <PROJECT_ID:MANAGEMENT_KEY>"

# Delete all tokens for a specific app
curl -X DELETE "https://api.descope.com/v1/mgmt/outbound/app/user/tokens?appId=google-contacts" \
  -H "Authorization: Bearer <PROJECT_ID:MANAGEMENT_KEY>"

# Delete all tokens for a specific user
curl -X DELETE "https://api.descope.com/v1/mgmt/outbound/app/user/tokens?userId=user-123" \
  -H "Authorization: Bearer <PROJECT_ID:MANAGEMENT_KEY>"