Recipe: Migrating from Hand-Rolled Connectors

Replace your per-service OAuth implementations and MCP servers with a single BlueNexus integration.

Before vs After

Before	After
OAuth implementation per service	One OAuth flow via BlueNexus
Token storage and encryption per service	BlueNexus manages all tokens (AES-256-GCM)
Per-service MCP server hosting	Single POST /mcp endpoint
Token refresh logic per service	Automatic token lifecycle management
Individual rate limit handling	Unified rate limiting
Context window filled with 100+ tools	Two tools: use-agent + list-connections

Migration Steps

Step 1: Inventory Your Current Integrations

List the services you currently support:

• Which services have OAuth?
• Which have API key auth?
• What operations does your app perform on each?

Check the Connector Catalog to verify BlueNexus supports your services.

Step 2: Create a BlueNexus Auth Client

curl -X POST https://api.bluenexus.ai/api/v1/auth-clients \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My App",
    "type": "confidential",
    "redirectUris": ["https://myapp.com/auth/bluenexus/callback"],
    "allowedScopes": ["universal-mcp-read-write", "connections", "account"]
  }'

Step 3: Replace Per-Service OAuth with BlueNexus OAuth

Before: Each service had its own OAuth flow:

// Google OAuth
app.get("/auth/google", googleOAuth.authorize);
app.get("/auth/google/callback", googleOAuth.handleCallback);

// Slack OAuth
app.get("/auth/slack", slackOAuth.authorize);
app.get("/auth/slack/callback", slackOAuth.handleCallback);

// Notion OAuth
app.get("/auth/notion", notionOAuth.authorize);
// ... repeated for every service

After: One OAuth flow for BlueNexus, then per-service connections:

// Single BlueNexus OAuth
app.get("/auth/bluenexus", bluenexusOAuth.authorize);
app.get("/auth/bluenexus/callback", bluenexusOAuth.handleCallback);

// Per-service connections are initiated via API
app.post("/connect/:providerId", async (req, res) => {
  const { authorizationUrl } = await fetch(
    "https://api.bluenexus.ai/api/v1/connections/initiate",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${userToken}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        providerId: req.params.providerId,
        redirectUrl: "https://myapp.com/connections/success",
      }),
    }
  ).then((r) => r.json());

  res.redirect(authorizationUrl);
});

Step 4: Replace API Calls with MCP

Before: Direct API calls per service:

// Google Calendar
const events = await googleClient.calendar.events.list({
  calendarId: "primary",
  timeMin: new Date().toISOString(),
});

// Slack messages
const messages = await slackClient.conversations.history({
  channel: "C123456",
});

After: Single MCP call:

const result = await fetch("https://api.bluenexus.ai/mcp", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${userToken}`,
    "Content-Type": "application/json",
    "X-Response-Format": "json",
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    method: "tools/call",
    params: {
      name: "use-agent",
      arguments: {
        prompt: "Get my calendar events for today and recent Slack messages from #engineering",
      },
    },
    id: "1",
  }),
}).then((r) => r.json());

Step 5: Remove Old Infrastructure

Once migrated and verified:

1. Remove per-service OAuth callback routes
2. Remove per-service token storage
3. Remove per-service MCP server deployments
4. Remove per-service API client libraries
5. Remove per-service token refresh cron jobs

Step 6: Migrate Users

For existing users with connected services:

1. Prompt them to connect their BlueNexus account (one-time)
2. Ask them to reconnect their services through BlueNexus
3. Deprecate old connections on a timeline

What You Keep

• Your app's business logic and UI
• Your user authentication system
• Your database (for app-specific data)

What BlueNexus Replaces

• Per-service OAuth implementation
• Token storage and encryption
• Token refresh management
• MCP server hosting
• Service-specific API client code
• Rate limit handling per service