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

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

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

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