Reading needs
datalyr:read and nothing else. Writing needs a named key or an OAuth
token that carries the matching write scope. The original workspace Agent key carries
datalyr:read forever, so no key already in circulation gained write power.
Which to pick
Pick MCP when a person drives the client and can complete a browser sign-in. The token is short-lived, and no key is stored anywhere. Pick the API when code runs without a person present. See Authentication to create a key.In-app chat is a third surface, and it never writes
The DATALYR dashboard has its own chat agent. It holds read tools and no write tools. It authenticates with the workspace Agent key, which carriesdatalyr:read only.
The panel has no consent screen, so nobody can grant it more. It can list, read, and run
dashboards and analyses. Its Save to Reports, Add to dashboard, and
Save as analysis buttons are a person’s clicks, not tools the model can call.
The MCP tools
Some tools read, and others change something or start work.report_missing_capability
records what no tool could do, never the question, and reads and changes no data. tools/list is the authority:
read it at the start of a session and branch on what comes back. Do not hard-code the
tool set.
Read tools
Ask with analytics_query
analytics_query answers any question of the form metric by dimension, filter, and
time. It takes a plan, not SQL. The workspace comes from your sign-in.
Funnels, retention, cohort LTV, and one person’s journey keep their own tools:
get_funnel, get_retention, get_ltv, and get_user.
Tools that write or start work
Write scopes
Any workspace member can use a write scope over OAuth, except the ads scopes: those need an
owner or admin. A named key with a write scope needs the owner to grant it. The ads scopes
are the levels on Access levels and who uploads. No ads
scope changes an ad account from chat: every ad write goes to a
review page, where an owner or admin uploads it.
The setup steps for Claude and Codex are on
Connect Claude or Codex.
What an agent can change, and what stops it
An agent can change conversion rules, trackable links, saved reports, dashboards, analyses, and custom metrics. It can create and revoke share links, and draft a container script. With an ads scope, it can also propose ads and ad changes for connected ad accounts, which a person uploads from a review page: see Agent ads. It cannot do anything else. Tracking domains, filter settings, team membership, and billing have no agent surface at all.
A container script is arbitrary JavaScript on every page of your site, next to your
checkout. That is why a leaked key can draft one and can never ship one.
Exports return a job, not a file
create_export answers with a job id. Poll get_export_status until the state is
completed, then read download.url.
Two clocks run on a finished export. The signed URL lasts one hour, so fetch it on use
rather than storing it. The file itself is deleted seven days after creation.
What the HTTP API adds
Every MCP data tool maps to a/v1 endpoint, so the API covers the same ground with three
extras an agent framework often wants. It also carries routes MCP does not expose at all,
including POST /v1/signup.
Reading a response safely
These five rules keep an agent from reporting a number that isn’t there.Sending events is a different credential
Reading and writing do not share a key or a host. An agent that also sends events uses the write key againsthttps://ingest.datalyr.com. See
Ingest API.
The write key reads nothing. Never point POST /attribution/lookup at an email address
a user typed into your own product.
Machine-readable docs
Verify
- Ask your client:
List my DATALYR workspaces. - Confirm the reply names the workspace you expect.
- Run the
curlon Authentication with your Agent key. - Confirm the response names the same workspace.
When it doesn’t work
Next
- Connect Claude or Codex: add the MCP server to your client.
- API reference: every endpoint and its parameters.
- Ingest API: send events over raw HTTP.