MCP Salesforce Bridge Reference

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

Delegated OAuth token
`auth_source=global_login_oauth` with viewer context in token claims.
Integration token with viewer context
Token already carries `viewer_id` and organisation context.
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

Outcome	Status	Behavior
Single matching active user	200	Tool executes immediately
Multiple matching active users	409	Returns candidates and requires `selected_user_id`
No active matching user	404	Returns `REVSPIRE_USER_NOT_FOUND`
Missing org context	401	Returns `MISSING_ORGANISATION_CONTEXT`
Invalid token mode	403	Returns `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.