OAuth Integration Guide

Start the OAuth flow

Call POST /oauth/{provider}/start from your backend. Two headers are required: your Account API Key (Authorization) and the API Key of the specific server you're connecting this user to (x-mewcp-key). The OAuth app used is always the one assigned to that server key, so there's no app selection in the request body. Pass the user's ID and, if you have a frontend, a callback URL. You can also pass optional user metadata, which MewCP stores alongside the credential for display in your dashboard:

Code
POST /oauth/google/start
Authorization: Bearer MEWCP_ACCT_API_KEY
x-mewcp-key: MEWCP_API_KEY

{
  "externalUserId": "user_123",
  "frontendCallbackUrl": "https://yourapp.com/oauth/callback",
  "externalUserMeta": {
    "name": "Jane Smith",
    "email": "jane@example.com",
    "username": "janesmith"
  }
}

If x-mewcp-key is missing, invalid, not a business-mode server key, or belongs to a different provider than {provider} in the path, the call fails with 401/400 before any OAuth URL is generated.

You get back:

Code
{
  "authUrl": "https://accounts.google.com/o/oauth2/auth?client_id=...",
  "state": "a3f9..."
}

The state value is internal: MewCP uses it to verify the callback. You do not need to store or validate it.

Open the auth URL for your user

If you have a frontend (web app):

Open the URL as a popup, the standard OAuth pattern. The popup must be opened from a user action (e.g. a button click), otherwise browsers will block it.

Code
// Open the popup on button click
const popup = window.open(authUrl, "mewcp-oauth", "width=500,height=650");

// Listen for the result message from your callback page
window.addEventListener("message", (event) => {
  if (event.origin !== window.location.origin) return;
  const { provider, success, error } = event.data;
  if (success) {
    // OAuth completed - update your UI
    console.log(`${provider} connected`);
  } else if (error) {
    console.error("OAuth failed:", error);
  }
});

After the user logs in, MewCP redirects the popup to your frontendCallbackUrl:

Your callback page needs to forward this result to the parent window and close the popup:

Code
// On your frontendCallbackUrl page
const params = new URLSearchParams(window.location.search);
window.opener?.postMessage(
  {
    provider: params.get("provider"),
    success: params.get("success") === "true",
    error: params.get("oauth_error") ?? null,
  },
  window.location.origin,
);
window.close();

If you prefer a full redirect (no popup):

Instead of opening a popup, redirect the user directly to the authUrl. After OAuth completes, MewCP redirects them back to your frontendCallbackUrl. Handle the result there as a normal page load:

Code
window.location.href = authUrl;

Code
// On your frontendCallbackUrl page
const params = new URLSearchParams(window.location.search);
if (params.get("success") === "true") {
  // show success, redirect to dashboard, etc.
}

If you have no frontend (local tools / server-only setups):

Simply open the authUrl in a browser, log in, and you're done. MewCP will show a "Connected" confirmation page with a close button. The credential is saved automatically, no further action needed.

Use the connection 🚀

Once connected, route your user's MCP requests through the gateway with their externalUserId in the header:

Code
x-external-user-id: user_123

MewCP resolves the stored credential and makes the authenticated call on their behalf.