MCP Server

The Dreamdata MCP Server exposes your Dreamdata data to MCP-aware AI assistants such as Claude, Claude Code, Cursor, ChatGPT, and Lovable. It lets you query and build on your Dreamdata data through your own agent without setting up any additional infrastructure.

You never need to call a tool by name. Describe what you want in plain language and your agent selects the right tools automatically. For the sake of completeness, the section below documents the tools the server exposes.

Available tools

The server exposes the tools below, grouped into four capabilities. This list is updated as functionality is added.

Run and explore reports

Tool	What it does	You ask things like
run_saved_report	Fetch and display the results from a saved Analytics Hub report.	"Run my quarterly ad performance report and plot the results."
run_saved_report_for_date_range	Run a saved report over a custom date range you specify, without changing the saved report itself.	"Run my pipeline report, but just for last month."
list_saved_reports	Browse the catalog of saved Analytics Hub reports in your Dreamdata account.	"What reports do I have about SQLs?"
list_report_metric_drilldown_entities	Drill into the contacts, companies, stages, or deals behind a specific metric value in a report.	"In the deal-stage report, which companies are behind the SQL column?"

Locate companies

Ask for the companies or contacts you care about in plain language. Your agent translates the question into an audience definition and runs it against your Dreamdata data, combining firmographics, behaviour (events and signals), and pipeline stages with time windows. The discovery tools in this group run behind the scenes to determine which filters and values are valid for your account; you will rarely invoke them directly.

Tool	What it does	You ask things like
list_my_accounts	Lists the Dreamdata accounts you can access (useful if you have access to multiple accounts).	"Which Dreamdata accounts can I access?"
run_audience_query	Finds the companies or contacts matching your criteria.	"Which companies reached SQL in the last 90 days in Europe?" "Which companies visited our pricing page at least 3 times this month?"
list_audiences	Browse the catalog of saved audiences in your Dreamdata account.	"What audiences do I have saved?"
get_audience_definition	Reuses an audience you have already saved in Dreamdata.	"Who's in my 'ICP – Engaged' audience right now?"
list_audience_filter_properties	Behind the scenes: discovers what your account can filter on (company, contact, and event properties plus pipeline stages per revenue model).	(usually invoked automatically)
list_audience_filter_values	Behind the scenes: finds the exact values a filter accepts.	(usually invoked automatically)
describe_audience_config_schema	Behind the scenes: supplies the full structure for building more complex audience definitions.	(usually invoked automatically)

Understand a company's journey

Once you have located the companies you care about, dig into how each one got where it is.

Tool	What it does	You ask things like
search_companies	Looks a company up by name.	"Show me Acme's journey."
get_company_journey	Fetches a company's full journey: summary, contacts, sessions, and touchpoints.	"What happened at Acme after they reached SQL?" "Compare the journeys of 3 companies that reached SQL this month."
list_company_journey_stages	Shows which pipeline stages a company reached, when, and at what value.	"When did Acme reach SQL, and what was the pipeline value?"

Build a report from scratch

Beyond running reports you have already saved, your agent can build a new Analytics Hub report from scratch — choosing the analysis type, metrics, filters, segmentation, and time window — and then run it in the conversation. The tools in this group run behind the scenes to discover what your account supports and assemble a valid report.

Reports your agent builds can also be saved to your Analytics Hub. Saving requires the optional Save Dreamdata Reports permission on the authorization screen (see Authorizing), and your agent always asks you to confirm before anything is saved.

Tool	What it does
report_builder_start	Behind the scenes: starts the guided report-building flow and lists the analysis types your account can build on.
report_builder_list_analysis_types report_builder_list_subjects report_builder_get_components	Behind the scenes: discover the analysis types, subjects, metrics, filters, and segmentation available for your report.
report_builder_resolve_calendar_period report_builder_resolve_rolling_window	Behind the scenes: translate a period like "Q1 2025" or "the last 45 days" into the report's time window.
report_builder_list_property_values report_builder_search_property_values	Behind the scenes: find and confirm the exact filter values to use.
report_builder_run_config	Behind the scenes: validates and runs the assembled report and returns the results.
report_builder_save_report	Saves a report your agent has built to your Analytics Hub. Requires the optional Save Dreamdata Reports permission, and only after you confirm the save.

Server URL

The MCP server uses a single URL for every account:

https://mcp.dreamdata.io/mcp

You sign in with your Dreamdata login when connecting — no account-specific URL is needed. If you have access to several Dreamdata accounts, your agent selects the right one per request (the list_my_accounts tool shows the options); with a single account you are connected automatically.

You can also find the URL, along with setup instructions for each supported client, in Dreamdata under Data Platform > Data Access, in the tile labeled MCP.

Connecting a client

Once you have the server URL, make it available to your agent. The steps below use Claude as the example; other clients follow a similar custom-connector flow.

Pro / Max (individual) plan

1. Go to Customize → Connectors.
2. Click +, then Add custom connector.
3. Enter the server URL: https://mcp.dreamdata.io/mcp.
4. Click Add. You are redirected to sign in via Dreamdata's OAuth flow — use your normal Dreamdata login.
5. Once authenticated, the connector is available in any conversation.

Team / Enterprise plans

Workspace owner — one-time setup:

1. Go to Organization settings → Connectors.
2. Click Add, hover Custom, and select Web.
3. Enter the server URL: https://mcp.dreamdata.io/mcp.
4. Click Add.

Team members — enable per user:

1. Go to Customize → Connectors.
2. Find the connector marked Custom.
3. Click Connect and complete the MCP login flow.

OAuth configuration

Most clients discover the server's OAuth endpoints automatically. If your client does not support OAuth endpoint discovery, configure the endpoints manually:

Setting	Value
Authorization URL	https://authenticate.dreamdata.io/oauth/2.1/authorize
Token URL	https://authenticate.dreamdata.io/oauth/2.1/token

OAuth 2.1 with SHA-256 PKCE required

The server only supports OAuth 2.1 authorization with SHA-256 PKCE. Clients that do not support OAuth 2.1 or SHA-256 PKCE cannot connect.

Registering a different client

The server recognises Claude, Claude Code, Lovable, Cursor, and ChatGPT. To register a client other than these, contact mcp-feedback@dreamdata.io to have it listed.

Authorizing

When you connect, Dreamdata asks you to authorize access. Two permissions are presented:

• Read Dreamdata Resources (required) — allows reading reports, customer journeys, and audiences.
• Save Dreamdata Reports (optional) — allows saving new reports your agent builds to your Analytics Hub. It cannot modify or delete existing reports. Grant it if you want to use report saving; your agent always confirms with you before saving.

Using the connector in a conversation

In any conversation, click the + button (lower-left of the composer), choose Connectors, and toggle Dreamdata on. The tools appear in your client's tool menu for that conversation.

Things to try

• "List all my saved reports."
• "Run the 'Pipeline by Source' report and show me the last 30 days."
• "Search for companies named Acme and show me the journey of the top match."
• "For the deal-stage report, drill down into the SQL column and list those companies."
• "Which companies reached SQL in the last 90 days in Europe?"
• "Compare the journeys of 3 companies that reached SQL this month."

Troubleshooting

If you run into errors, your agent may pass along an error code that helps pinpoint what to do.

• No tools appear after connecting. If you see "MCP server is not enabled for this user. Contact your Dreamdata account owner", email mcp-feedback@dreamdata.io.
• 401 Unauthorized. Your session has expired or the token is invalid. Disconnect and reconnect the connector to re-authenticate.
• 403 Forbidden. You are authenticated but not a member of the Dreamdata account being queried. Ask your agent to run list_my_accounts to see which accounts you can access, or contact your Dreamdata account owner.
• 502 from the connector. The Dreamdata internal API is unreachable. This is a server-side problem; contact mcp-feedback@dreamdata.io.

Feedback

We want to hear which capabilities and workflows you would like to see next. Send feedback to mcp-feedback@dreamdata.io.