Rolli
Rolli API Documentation

Rolli MCP Server

The Rolli MCP Server exposes the full Rolli Experts & IQ API through the Model Context Protocol (MCP), enabling ChatGPT, Cursor, or any MCP-enabled client to perform expert searches and social intelligence queries without manually issuing HTTP requests.

What is the Rolli MCP Server?

MCP (Model Context Protocol) allows tools to run directly inside ChatGPT or other AI-powered development environments. The Rolli MCP Server wraps all Rolli API endpoints into MCP tools, enabling you to:

  • Submit expert searches
  • Run keyword-based social media searches
  • Run user-based social media searches
  • Fetch posts, analytics, topic trees, and more
  • Launch Rolli Agent investigations and manage scheduled reports

Each tool corresponds to an API endpoint, and for all submit search tools, the MCP returns the full results immediately, equivalent to calling: 

GET /api/search/{id}

or

GET /api/iq/keyword_search/{id}

The MCP abstracts away polling—so you receive complete data when the search finishes.

Adding the Rolli MCP to AI Clients

Replace YOUR_ROLLI_API_TOKEN and YOUR_ROLLI_API_USER with your provided credentials. You can rotate the token at any time.

Claude Desktop / ChatGPT / Cursor / Windsurf / VS Code

Add to your MCP settings:

{
  "mcpServers": {
    "rolli": {
      "command": "npx",
      "args": ["-y", "@rolli/mcp"],
      "env": {
        "ROLLI_API_TOKEN": "YOUR_ROLLI_API_TOKEN",
        "ROLLI_USER_ID": "YOUR_ROLLI_API_USER"
      }
    }
  }
}

Authentication

Requests made through the MCP Server automatically include the correct authentication headers for the API. You do not need to manually set X-ROLLI-TOKEN or X-ROLLI-USER-ID.

Your MCP client forwards the Rolli's authorization headers into the server: 

X-ROLLI-TOKEN: YOUR_ROLLI_API_TOKEN

X-ROLLI-USER-ID: YOUR_ROLLI_API_USER

No other credentials are required.

Exposed Tools

The MCP server exposes the following tools, which map 1:1 to Rolli's API endpoints:

Expert Search Tools

  • submit_expert_search — submits a POST /api/search request and returns the full results
  • get_expert_search — GET /api/search/{id} to retrieve an Expert Search by ID
  • get_expert_searches — GET /api/search to list all Expert Searches

Rolli IQ – Keyword Search Tools

  • submit_keyword_search — submits a POST /api/iq/keyword_search request and returns the full results
  • get_keyword_search — GET /api/iq/keyword_search/{id} to retrieve a Keyword Search by ID
  • get_keyword_searches — GET /api/iq/keyword_search to list all Keyword Searches
  • get_keyword_search_topic_tree — GET /api/iq/keyword_search/{id}/topic_tree to fetch the topic tree for a Keyword Search
  • get_keyword_search_posts_data — GET /api/iq/keyword_search/{id}/posts_data to fetch posts data for a Keyword Search

Rolli IQ – User Search Tools

  • submit_user_search — submits a POST /api/iq/user_search request and returns full results
  • get_user_search — GET /api/iq/user_search/{id} to retrieve a User Search by ID
  • get_user_searches — GET /api/iq/user_search to list all User Searches
  • get_user_search_posts_data — GET /api/iq/user_search/{id}/posts_data to fetch posts data for a User Search

Rolli Agent – Run Tools

  • start_agent_run — submits a POST /api/v1/runs request and polls until the run is complete, returning the full report
  • list_agent_runs — GET /api/v1/runs to list your Agent runs (paginated, filterable by status)
  • get_agent_run — GET /api/v1/runs/{id} to retrieve a run by ID (progress while running, full results once complete)
  • cancel_agent_run — POST /api/v1/runs/{id}/cancel to cancel a pending or running Agent run
  • rerun_agent_run — POST /api/v1/runs/{id}/rerun to re-enqueue a failed, waiting, or stuck run
  • update_agent_run — PATCH /api/v1/runs/{id} to rename or pin a run
  • delete_agent_run — DELETE /api/v1/runs/{id} to soft-delete a completed or failed run

Rolli Agent – Schedule Tools

  • create_agent_schedule — POST /api/v1/schedules to create a recurring Agent run (daily, weekly, monthly, etc.)
  • list_agent_schedules — GET /api/v1/schedules to list your schedules
  • get_agent_schedule — GET /api/v1/schedules/{id} to retrieve a schedule by ID
  • update_agent_schedule — PATCH /api/v1/schedules/{id} to update a schedule's question, cadence, or other settings
  • pause_agent_schedule — POST /api/v1/schedules/{id}/pause to pause a schedule
  • resume_agent_schedule — POST /api/v1/schedules/{id}/resume to resume a paused schedule
  • delete_agent_schedule — DELETE /api/v1/schedules/{id} to delete a schedule
  • list_agent_schedule_runs — GET /api/v1/schedules/{id}/runs to list the runs produced by a schedule

Integration Setup

You can manage and update your Rolli API integration settings through the MCP server. To update the webhook URL for Rolli API or view your integration setup, use the following tools:

Integration Setup Tools

  • get_integration_setup — retrieves the current integration setup information for your Rolli API
  • update_integration_setup — updates the integration setup, including the webhook URL

Usage Statistics

Monitor your usage statistics for the Rolli API through these tools:

Usage Tools

  • usage — gets the general usage statistics for your Rolli API account
  • get_usage_by_month — retrieves usage statistics by month for your Rolli API

Example Workflow in ChatGPT / Cursor

After adding the MCP, you can simply type:

"Search for experts in AI ethics"

ChatGPT will call:

submit_expert_search

For keyword-based social media searches, try:

"Analyze conversations about election integrity across Twitter and Reddit"

ChatGPT will call:

submit_keyword_search

For user-based searches, you can do:

"Find users discussing privacy laws on social media"

ChatGPT will call:

submit_user_search

You will receive full results when the search is completed.

Advantages of MCP vs REST API

  • No need for credentials in your code — only in MCP config
  • No polling — submit tools return full, completed results
  • Tools function like natural language actions
  • Ideal for ChatGPT Agents, Cursor workflows, and automation

Rolli Remote MCP Server (Hosted)

Prefer not to install anything locally? Use the hosted Rolli MCP server at https://mcp.rolli.ai/mcp. Sign-in is browser-based — no API token to copy and rotate.

The remote server runs on Cloudflare Workers and uses MCP's Streamable HTTP transport with OAuth 2.0 + PKCE. On first connection your MCP client opens a browser window where you sign in to Rolli; the server then issues a scoped access token that's encrypted at rest and tied to the MCP session.

Adding the Remote MCP to AI Clients

Add to your MCP settings (Claude Desktop, Cursor, Windsurf, VS Code, etc.):

{
  "mcpServers": {
    "rolli": {
      "url": "https://mcp.rolli.ai/mcp"
    }
  }
}

On first connect:

  1. Your client performs Dynamic Client Registration against the server
  2. You're redirected to app.rolli.ai to sign in
  3. After authorization, the client stores the OAuth tokens and exposes the Rolli tools

Revoke access at any time from your AI client's connector settings, or directly inside Rolli IQ. There is no API token or user ID to manage.

Local vs Remote — When to Use Which

Local (@rolli/mcp)Best when you already have an API token, want stdio transport, or need to run offline / behind a firewall. Token is stored in your config file.
Remote (mcp.rolli.ai)Best when you want zero-install setup, browser-based sign-in, or are sharing a device with colleagues. No token in config.

Both servers expose the same set of tools (expert search, keyword search, user search, topic tree, posts, integration setup, usage, Rolli Agent runs and schedules) — pick whichever auth model suits you.