Skip to main content

MCP Server

DashX ships a Model Context Protocol (MCP) server, so AI agents like Claude Code, Claude Desktop, Cursor, and Codex can work with your workspace in natural language - "show me my WhatsApp chats", "how many open issues are in the Onboarding space?", "add a note to these tickets".

The agent does the reasoning; DashX exposes your data as a set of permission-scoped tools. Every request runs through the same authorization and policy layer as the rest of the API, so an agent only ever sees and does what you allowed it to. Analytics counts are the exception noted below.

Beta

The MCP server is in beta. Tools and behavior may change. Connect it to a non-production environment first.

Endpoint​

https://api.dashx.com/mcp

Self-hosted? Use your own host with the /mcp path.

Quick Setup​

Add the server to your client, then sign in to DashX in the browser window it opens. There are no keys to copy: the client gets its own access, which you approve and can disconnect at any time.

Register the server:

claude mcp add --transport http dashx https://api.dashx.com/mcp

Then run /mcp inside Claude Code and follow the steps in your browser to sign in. You can also sign in from your shell with claude mcp login dashx.

Add --scope user to make dashx available in every Claude Code session, not just this project.

Choosing What an Agent Can Do​

When you sign in, DashX asks what to allow the app:

SettingOptions
AccessRead only, Read & write, or Custom to set each app below separately
PlannerRead issues; write: create and edit issues, change statuses, assign issues and add internal notes
MessagingRead conversations and messages; write: send public replies to customers by email
ViewsRead your views; write: edit views you have open in the assistant
AnalyticsAnalyze records and reports. Analyzing issues or conversations also needs read access to Planner or Messaging. Counts cover the whole environment you connected and aren't narrowed by row-level limits on your own account or by the spaces you select. With selected spaces, issue and conversation analysis is refused; accounts, groups and events can still be analyzed
AI HubRead AI agents, their logs and insights. Logs and insights cover every space's conversations, so they're refused when you select spaces
DataRead contacts, events, custom resources and their records
SpacesAll spaces or Only ones I select. With selected spaces, the agent sees only issues in them and the conversations and messages tied to those issues, create_issue must name one of them, analyze_records can't analyze issues or conversations (the list and count tools still work), and listing events and AI agent logs and insights are refused
EnvironmentsAll environments or Only ones I select

AI Hub and Data are read only. Access starts at Read only unless your client asked for specific access. For an agent that creates or edits issues, sends replies or edits views, pick Read & write, or choose Custom and set Write on the apps it needs.

Every connection lists every tool. A tool outside the access you granted is refused when the agent calls it: the server tells your client which access is missing, and clients that support it ask you to approve more. get_current_context reports the access a connection is missing, so an agent can check before it calls. get_current_context, describe_resource, search_docs, list_environments, list_groups and switch_environment need no app access.

The app never gets more than your own account can do.

A sign-in lasts 30 days by default (your workspace may be set to a shorter period), then your client asks you to sign in again. Changing or resetting your password, changing your email, turning two-factor authentication on or off, or signing out your other sessions disconnects every connected app right away.

To review or remove access, open your account menu → Settings → Connected Apps and click Disconnect. The list shows apps for the workspace you're in, so check each workspace you connected.

Environments​

A connection starts in a non-live environment when you allowed one: the one you're viewing in the dashboard if it's allowed, otherwise the first allowed non-live one. The sign-in page says which (Starts in Staging). If you allowed only the live environment, it starts there. If you allowed more than one, ask the agent to switch ("switch to staging"); it uses switch_environment, and later calls on that connection run there until the client reconnects. A new chat doesn't always reset it, since some clients keep one connection across chats, so ask the agent which environment it's in, or pin one with ?environment= (below). Agents are asked to check with you before switching into a live environment.

To connect another workspace, add the server again under a different name with ?workspace=<identifier> on the URL (for example https://api.dashx.com/mcp?workspace=acme). Sign-in then goes straight to that workspace. Adding ?environment=<identifier> starts every chat in that environment and turns off switching. The environment must be one you allowed when signing in, or the connection is refused.

Clients Without Sign-In​

For a client or script that can't open a browser, open your account menu → Settings → Access Tokens, create a token, and send it as a bearer token.

Claude Code:

claude mcp add --transport http dashx https://api.dashx.com/mcp \
  --header "Authorization: Bearer $DASHX_ACCESS_TOKEN"

Cursor:

~/.cursor/mcp.json
{
  "mcpServers": {
    "dashx": {
      "url": "https://api.dashx.com/mcp",
      "headers": { "Authorization": "Bearer ${env:DASHX_ACCESS_TOKEN}" }
    }
  }
}

Codex:

~/.codex/config.toml
[mcp_servers.dashx]
url = "https://api.dashx.com/mcp"
bearer_token_env_var = "DASHX_ACCESS_TOKEN"

The token acts as your account in every space and environment you can reach, lists every tool (your account's permissions decide each call), and expires after the lifetime you chose when creating it (1, 7, 15 or 30 days, 7 by default). You can have up to 25 active tokens. Treat it like a password and revoke it if it leaks.

A token connection works in one environment and can't use switch_environment. Pick the environment with ?environment=<identifier> on the URL (for example https://api.dashx.com/mcp?environment=staging) or an X-Target-Environment: <identifier> header. Without either, it works in your live environment (Production by default), unlike a browser sign-in, which starts in a non-live environment when you allowed one.

Connections that send an API key pair (X-Public-Key / X-Private-Key) keep working.

Available Tools​

Reading - these never change data:

ToolDescription
list_spacesList spaces (such as Support or Onboarding) - resolve a space name before filtering issues by spaceId.
list_issuesList issues / tickets. Filter by space, type, status, assignee, group, priority, title, or dates.
aggregate_issuesCount issues matching a filter.
list_issue_typesList issue types (resolve issue type ids to names).
list_issue_statusesList issue statuses (the label/kind for an issue's status).
list_assigneesList the members and AI agents issues can be assigned to.
list_groupsList groups (the teams / queues issues and conversations are assigned to).
list_conversationsList conversations across channels (chat, WhatsApp, email, SMS, ...), with rich filters.
aggregate_conversationsCount conversations matching a filter.
list_messagesRead one conversation's transcript: pass { "conversationId": "<uuid>" } as the filter. Without conversationId it lists broadcast (campaign) messages only.
aggregate_messagesCount one conversation's messages (filter by conversationId), or broadcast messages when no conversationId is given. For chat volume, count conversations instead.
analyze_recordsFast counts and trends over issues, conversations, accounts, groups or events - grouped by columns and/or a time bucket (day/week/month).
list_environmentsList the environments this connection can use.
get_current_contextShow who the connection acts as, its workspace and environment, how it's connected (oauth, token or key_pair), its access and the access it's missing (missingScopes), and its space or environment limits. Agents call it first to orient themselves.
list_accountsList accounts: customers and contacts, and members. Needs a search of 3 or more characters (part of a name, or an exact uid, email or phone), or a filter with eq or in on id, uid, email or phone. Filtering by kind alone works only for members (MEMBER). Results can't be ordered.
get_accountRead one account, with its custom attributes.
list_viewsList your views (dashboards, lists and pages), 20 at most per page.
describe_resourceShow what issues, conversations, messages, accounts, groups, spaces, views, issue types, issue statuses or environments can be filtered and ordered by.
search_docsSearch the DashX documentation and return matching pages with links. If docs search isn't set up on the server, it says so and points to docs.dashx.com.
get_ai_agentRead an AI agent: its newest versions (status, model, interaction mode) and where it's deployed.
list_ai_agent_logsList one AI agent's runs in this environment (pass the agent's id), newest first, 20 per page: status, failure category (such as rate limited, timeout or provider rejected), model, duration, tokens and cost, and the conversation each belongs to. Covers the last day by default and 7 days at most, and paging stops at 500 runs. Prompts and transcripts aren't returned; the agent reads the conversation with list_messages.
get_ai_agent_insightsSummarize one AI agent's performance in this environment, as on its Insights page: turns, conversations, handoffs, failures, tokens, cost and latency, per version and per day, with failures counted in broad categories (list_ai_agent_logs gives each run's finer one). Covers the last 7 days by default and 14 days at most.
list_eventsList tracked events in this environment, newest first, with their event type, account and data. Covers the last 7 days by default and 31 days at most, and orders by createdAt or timestamp only. Built-in DashX event types return no data. A data filter needs an eventTypeId naming one of your workspace's own event types. For counts and trends, use analyze_records. Refused when you select spaces, since events can carry issues from any space.
list_event_typesList your workspace's event types and when each was last received. Built-in types (one per DashX operation outcome) are listed only when searching or when asked for.
list_custom_resourcesList your custom resources (your own data types, such as orders) and their fields, including which can be filtered or ordered by. Returns 10 resources per page; fieldsTruncated marks a resource whose field list was cut short.
list_recordsList one custom resource's records, read from the database or API it's connected to. Filter and order by the resource's fields. Each record's fields come under data. Returns 20 records by default and at most 50 per page. A resource shared across environments is read from your live environment, so the connection must be allowed to use it.

Acting - these need write access:

ToolDescription
create_issueCreate an issue.
update_issueChange the title, description, priority, due date, group or labels of one or more issues. Only the fields passed change, and labels replace the issue's current ones. Titles can be 255 characters at most, and an issue can get 20 labels at most, 100 characters each. Blank labels and a blank description are refused: pass [] to remove every label, or null to clear the description, due date or group. The preview shows each issue's current and new values.
change_issue_statusChange the status of one or more issues.
assign_issueAssign issues to a member or AI agent, or unassign them.
create_internal_noteAdd an internal note to issues (only your team sees it).
create_public_replyEmail a public reply to each issue's requester - customer-visible and can't be unsent. Issues whose type doesn't allow public replies, or whose space has no email reply set up, are skipped and the preview says why.

switch_environment moves the connection to another environment you allowed. It needs no write access, but clients ask before running it because later calls run there.

get_view and patch_view are used by the DashX assistant to read and edit the view you have open there. Other clients have no open view to pass them.

A change to a single issue runs immediately. Tools that change several issues at once (up to 200 per call) show a preview first and only act when the agent confirms it, so you can check the list before anything changes. Locked issues are skipped and the preview says why; only internal notes still go on them. The preview's confirmation is valid for 10 minutes. An issue whose status, assignee or updated fields changed after the preview is left as it is, and the agent previews again. For replies, notes, status changes, assignments and updates, more than five one-issue calls of the same tool in a minute are refused, so the agent has to pass the issues together and preview them. A reply or note identical to one sent through these tools on the same issue within about a day is skipped, so it's never sent twice.

Every tool carries standard MCP hints (readOnlyHint, destructiveHint), so clients that support them can skip approval for reads and ask before writes.

Filtering​

The list and count tools take a filter object. Keys are AND-combined; each key takes one operator, like { "eq": ... } or { "in": [...] }. For a range, combine bounds with and:

{ "and": [{ "createdAt": { "gte": "2026-01-01" } }, { "createdAt": { "lt": "2026-02-01" } }] }

The agent constructs these from your request - you rarely write them by hand. When it's unsure which keys a resource takes, it checks with describe_resource (or list_custom_resources for your own resources).

List tools return 50 rows by default; limit goes up to 100, and page fetches more. Some return fewer: AI agent logs 20 per page, views 20 at most, custom resources 10, and custom records 20 by default and 50 at most, since they're read from your own database or API. For accounts, views, events, event types, custom resources, records and AI agent logs, paging stops at the first 2,000 results (500 for AI agent logs), so narrow the filter or time window instead. For totals, use the count tools. A result over 96 KB comes back cut short, with a note telling the agent to narrow the filter or fetch the next page.

Example Prompts​

Once connected, just talk to it in your client - the agent picks the right tools. A base set to start from:

Conversations & chats

  • "Show me my WhatsApp chats from this week."
  • "How many unanswered conversations do I have right now?"
  • "Read conversation <id> and summarize what the customer needs."

Issues & tickets

  • "List the open issues in the Onboarding space."
  • "Which urgent issues are unassigned?"
  • "Show me the issues assigned to the Chat Team group."
  • "Move these three tickets to Done and add a note saying why."
  • "Set these tickets to high priority and due Friday."

AI agents, contacts & data

  • "How did the Support agent do this week, and why did its runs fail yesterday?"
  • "Find the contact with email jane@example.com and show their custom attributes."
  • "Show the 20 most recent orders over 1000."

Trends & breakdowns (analytics)

  • "How many conversations per day this month, by channel?"
  • "Break down issues by priority."
  • "How many new accounts per month this year, by kind?"

Exploring your workspace

  • "What spaces, environments and groups do we have?"
  • "List our issue types and statuses."
tip

Mix and match - "break down this week's urgent issues by status" will list issue statuses to resolve names, then aggregate. Looking up spaces, statuses and issue types needs Planner read access. Be specific about the space, time range and channel for the sharpest answers.

Security & Scoping​

  • An agent acts as you, limited to what you approved when you signed in: the apps, read or write, and the spaces and environments you selected.
  • Writes that reach customers (public replies) need Messaging: Write; everything else that changes data needs write access to its app. Replies, notes, status changes and assignments act on issues, so the agent also needs Planner read access to find them.
  • Click Disconnect on an app under your account menu → Settings → Connected Apps to cut off its access immediately.