Revspire Resources

MCP API Reference

This page describes MCP transport and endpoint contracts in Revspire.

Base URL

Use the Backend Base URL displayed in Revspire > Setup > OAuth.

Example:
https://demo.apac1.my.api.revspire.io

Endpoints

Endpoint Auth Purpose
GET /mcp/health No Health + protocol + tool names
GET /mcp OAuth MCP transport metadata + tool catalog
POST /mcp OAuth JSON-RPC and direct tool invocation
POST /mcp/salesforce/tools/call OAuth Salesforce bridge execution

JSON-RPC Methods

  • initialize
  • tools/list
  • tools/call

How To Get the Tool List

Use either of these two options:

  1. Preferred for MCP clients: POST /mcp with JSON-RPC method tools/list
  2. Simple transport discovery: GET /mcp and read data.tools

Endpoint to list tools (JSON-RPC)

POST https://<backend_base_url>/mcp
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": "tools-1",
  "method": "tools/list",
  "params": {}
}

Initialize

curl -X POST "https://<backend_base_url>/mcp" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{}}'

Tools List

curl -X POST "https://<backend_base_url>/mcp" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"2","method":"tools/list","params":{}}'

Tools Call (JSON-RPC)

curl -X POST "https://<backend_base_url>/mcp" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"3","method":"tools/call","params":{"name":"dealroom.list","arguments":{"page":1,"page_size":50}}}'

Direct Tool Mode

The same POST /mcp endpoint also supports direct payload mode:

{
  "tool": "content.list_dashboard",
  "arguments": {}
}

Standard Execution Envelope

{
  "success": true,
  "data": {},
  "error": null,
  "request_id": "...",
  "permission_context": {
    "viewer_id": "...",
    "organisation_id": "...",
    "token_client": 0,
    "required_scopes": ["revspire.agentforce.tools.read"]
  }
}

Pagination Contract

List tools return a consistent pagination block under data.pagination.

{
  "items": [],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total_items": 318,
    "total_pages": 7,
    "has_more": true,
    "next_page": 2,
    "total_items_known": true,
    "total_pages_known": true
  }
}

Default page size is 50 (max 200). Continue fetching while has_more=true using next_page.

Request Identity Rules

  • viewer_id and organisation_id are resolved from token context.
  • If caller supplies conflicting IDs, MCP rejects request with identity mismatch.
  • Tool validators enforce schema before route execution.

May 2026 API Update

  • New MCP tool families added: folder discovery, safe content access metadata, and full content change request workflows.
  • Search and dashboard responses now include internal deep links by default.
  • MCP response now consistently echoes required_scopes and accepted_scopes in permission_context.

Internal Link Derivation

When MCP receives backend host context such as demo.apac1.my.api.revspire.io, it derives frontend app links in this format:

https://demo.my.revspire.io/content/content-portal?contentId=<content_id>
https://demo.my.revspire.io/content/content-portal?folderId=<folder_id>

Updated Tool Groups

Group Tools
Search + Access search.query_content, folder.find, content.get_thumbnails, content.get_access_info
Content Requests content_request.create, content_request.list_my, content_request.list_queue, content_request.report, content_request.list_assignable_users, content_request.assign, content_request.respond, content_request.approve, content_request.reject, content_request.revoke, content_request.add_comment
Revenue Intelligence content.get_revenue_influence, content.get_top_performing
Reporting & Dashboards reporting.metadata.get, reporting.types.list, reporting.preview.run, reporting.save, reporting.saved.*, reporting.catalog.*, reporting.dashboard.*

Standard Permission Context (Current)

{
  "permission_context": {
    "viewer_id": "...",
    "organisation_id": "...",
    "token_client": 0,
    "required_scopes": ["revspire.agentforce.tools.read"],
    "accepted_scopes": [
      "revspire.agentforce.tools.read",
      "revspire.mcp.tools.read"
    ]
  }
}

Common Content Request Endpoints Through MCP

MCP Tool Backend Route Primary Permission(s)
content_request.create /send-change-request Request Content
content_request.list_queue / content_request.report /approvals/change-requests/list Request Content, Assign Content Request, View All Content Requests
content_request.assign /assign-change-request Assign Content Request
content_request.respond /respond-change-request Request Content, Assign Content Request, View All Content Requests
content_request.approve /accept-change-request Request Content, Assign Content Request, View All Content Requests

Field-Level Tool Docs

Per-field argument definitions and rich request examples are maintained in Tool Reference. Use those pages when building MCP clients (ChatGPT, Claude, n8n, Zapier, HubSpot, and custom agents).

  • Each tool entry includes argument type, required flag, description, and a concrete example value.
  • Each tool entry includes JSON-RPC request examples plus success/error envelope examples.
  • Tool docs are aligned to the backend MCP schema in mcpToolRegistry.js.

Visual Summary Contract (Chat-Friendly)

MCP now includes optional visual_summary at the tool execution envelope level for numeric datasets, enabling compact chart rendering in ChatGPT/Codex.

  • Tabular numeric responses render bar/table style summaries.
  • Summary-object responses (without row arrays) render KPI-style summaries.
  • When no numeric signals exist, visual_summary is returned as null.
{
  "success": true,
  "data": { ... },
  "visual_summary": {
    "can_render_visual": true,
    "recommended_chart": "bar",
    "dimension_key": "owner",
    "metric_keys": ["amount"],
    "kpis": [{"metric_label": "amount", "aggregate": 1240000}],
    "series": [{"metric_label": "amount", "points": [{"x": "Alice", "y": 120000}]}]
  },
  "error": null,
  "request_id": "...",
  "permission_context": { ... }
}

Reporting Lifecycle Tool Family

Stage MCP Tools
Build & Preview reporting.metadata.get, reporting.types.list, reporting.preview.run
Save & Open reporting.save, reporting.saved.list, reporting.saved.get, reporting.link.open
Access Management reporting.saved.request_access, reporting.saved.respond_access
Catalog Management reporting.catalog.* (folders, reports, dashboards, sharing, move/clone/delete)
Dashboard Operations reporting.dashboard.get, reporting.dashboard.save, reporting.dashboard.request_access