Data 360 MCP Server

A Model Context Protocol (MCP) server that connects Cursor (or any MCP-compatible AI client) to Salesforce Data Cloud / Data 360, enabling natural-language-driven exploration, querying, and full configuration management of your Data 360 instance.

Built on forcedotcom/datacloud-mcp-query — extended with a full admin CRUD layer, a runtime Swagger spec client, and AI-guided API schema lookup.

What's New vs. the Original

The upstream forcedotcom/datacloud-mcp-query provides Scope 1 (catalog) and Scope 2 (query). This fork adds:

No changes to Salesforce org setup. The same Connected App, OAuth scopes, and authentication flow from the original repo apply without modification.

Features

Scope 1 — Catalog / Metadata

• list_tables — List all queryable Data Cloud tables

• describe_table — Describe the columns of a table

Scope 2 — Query

• query — Execute SQL queries against Data Cloud (PostgreSQL dialect)

Scope 2b — API Schema Lookup (new)

• get_api_schema — Fetches the live Data 360 Connect API Swagger spec at runtime and returns the correct request-body JSON Schema + example for any create/update tool. Always call this before a create_* or update_* tool to get exact field names, types, and required fields.

Scope 3 — Data & Process Configuration (new)

Adding to Cursor

1. Clone this repository to your local machine.

2. Install dependencies:

   pip install -r requirements.txt

3. (Optional but recommended) Download the Salesforce Connect API Swagger spec locally for offline use:

   # Obtain cdp-connect-api-Swagger.yaml from the Salesforce developer portal
   # and place it anywhere accessible, e.g. ~/Downloads/cdp-connect-api-Swagger.yaml

4. Open Cursor Settings → MCP → Add new global MCP server and paste:

   "mcpServers": {
     "datacloud": {
       "command": "<path to python>",
       "args": ["<full path to>/server.py"],
       "env": {
         "SF_CLIENT_ID": "<Client Id>",
         "SF_CLIENT_SECRET": "<Client Secret>",
         "SWAGGER_PATH": "<absolute path to>/cdp-connect-api-Swagger.yaml"
       },
       "disabled": false,
       "autoApprove": [
         "list_tables", "describe_table",
         "get_api_schema",
         "list_data_streams", "get_data_stream",
         "list_dlos", "get_dlo",
         "list_dmos", "get_dmo",
         "list_segments", "get_segment",
         "list_identity_resolution_rulesets", "get_identity_resolution_ruleset",
         "list_calculated_insights", "get_calculated_insight",
         "list_activation_targets", "get_activation_target",
         "list_activations", "get_activation"
       ]
     }
   }

5. Enable the MCP server and click Refresh to see the full tool list.

Configuration

Required Environment Variables

Optional Environment Variables

See Connected App Setup Guide for instructions on creating the Connected App.

Required OAuth Scopes

The Connected App must have the following OAuth scopes enabled:

Note: cdp_admin_api is required for all Scope 3 tools. If this scope is missing from your Connected App, add it and re-authenticate.

Authentication

The server implements OAuth 2.0 with PKCE (unchanged from the original):

• Automatically opens a browser window for the first authentication

• Handles token exchange and maintains the session

• Token expires after 110 minutes and is automatically refreshed on next tool call

How get_api_schema Works

Before calling any create_* or update_* tool, the AI agent should call get_api_schema with the tool name to retrieve the live API contract:

get_api_schema("create_calculated_insight")
→ {
    "summary": "Create calculated insights",
    "example": {
      "apiName": "...",
      "displayName": "...",
      "definitionType": "CALCULATED_METRIC",
      "dataSpaceName": "default",
      "expression": "SELECT ... FROM ... GROUP BY ...",
      "publishScheduleInterval": "Six",
      "publishScheduleStartDateTime": "2025-12-11T12:00"
    },
    "schema": { ... }
  }

The spec is fetched from the Salesforce static CDN (SWAGGER_URL). If that URL is unreachable, it falls back to a local YAML file at SWAGGER_PATH. The parsed spec is cached in-process for the lifetime of the server — no repeated network calls.

Valid tool_name values for get_api_schema:

Example Natural Language Prompts

Once connected you can ask Cursor things like:

Querying data:

• "List all tables in Data Cloud"

• "How many opportunities are there per account?"

• "Show me total opportunity amount by stage"

Calculated Insights:

• "Create a calculated insight to track total opportunities by account"

• "Create a monthly opportunity trend insight grouped by account and creation month"

• "Refresh the TotalOpportunitiesByAccount calculated insight"

Segments:

• "Create a segment targeting US accounts with non-closed opportunity amount greater than $10,000"

• "List all active segments"

• "Publish the HighValueAccounts segment"

Data Streams & DLOs:

• "List all data streams and show which ones haven't run recently"

• "Deploy the Case_Home data stream"

• "Show me all Data Lake Objects and their categories"

Identity Resolution:

• "Run identity resolution for the default ruleset"

• "List all identity resolution rulesets and their last run status"

File Structure

datacloud-mcp-query/
├── server.py                  # MCP server — all tool definitions (Scopes 1, 2, 2b, 3)
├── connect_api_dc_sql.py      # SQL query execution client (Scope 2)
├── connect_api_dc_admin.py    # Admin REST API client (Scope 3) ← new
├── swagger_client.py          # Runtime Swagger spec loader — powers get_api_schema ← new
├── oauth.py                   # OAuth 2.0 + PKCE authentication
├── requirements.txt           # Python dependencies (includes pyyaml) ← updated
├── README.md
├── CONNECTED_APP_SETUP.md
└── .gitignore                 # Excludes .env, .cursor/, local Swagger file

Security Notes

• No credentials are stored in this repository. All secrets are passed via environment variables.

• .env files, the Cursor project folder (.cursor/), and any local copy of the Swagger spec (cdp-connect-api-Swagger.yaml) are excluded via .gitignore.

• The SWAGGER_PATH env var pointing to your local Swagger copy is set in your Cursor MCP config (not committed).

License

Apache-2.0 — see LICENSE.txt