MCP Salesforce Bridge Reference

Last updated:

This page documents the Salesforce bridge endpoint and identity resolution behavior.

Endpoint

POST /mcp/salesforce/tools/call

Why This Endpoint Exists

It lets Salesforce-driven surfaces execute MCP tools while enforcing Revspire organisation/user context and scope checks.

Accepted Identity Modes

  1. Delegated OAuth token `auth_source=global_login_oauth` with viewer context in token claims.
  2. Integration token with viewer context Token already carries `viewer_id` and organisation context.
  3. Integration token + Salesforce email lookup Provide `salesforce_user_email` and the bridge resolves active user in org.

Request Body

{
  "tool_name": "dealroom.list",
  "salesforce_user_email": "user@company.com",
  "selected_user_id": "IGH...", 
  "arguments": {
    "page": 1,
    "page_size": 20
  }
}

User Resolution Outcomes

OutcomeStatusBehavior
Single matching active user200Tool executes immediately
Multiple matching active users409Returns candidates and requires selected_user_id
No active matching user404Returns REVSPIRE_USER_NOT_FOUND
Missing org context401Returns MISSING_ORGANISATION_CONTEXT
Invalid token mode403Returns INVALID_TOKEN_TYPE

Multiple User Selection Example

Initial response when multiple users match:

{
  "success": false,
  "data": {
    "requires_user_selection": true,
    "user_candidates": [
      { "id": "IGH...", "username": "...", "email": "..." }
    ]
  },
  "error": {
    "code": "USER_SELECTION_REQUIRED",
    "status": 409
  }
}

Retry with selected_user_id from candidates.

Operational Notes

  • The bridge still uses full MCP tool validation, scope checks, rate limits, and idempotency.
  • Returned payload includes salesforce_context with resolved user and identification source.