Operating the API and MCP | ATX AnalyticsTable Docs

Operating the API and MCPEvery server setting for the API and MCP, network exposure, audit records, Prometheus metrics, and what each common error message means. On a server installation, publish the backend only through your reverse proxy (TLS, WAF), as the Server installation page describes. The API and MCP add no listener and no port of their own. An API gateway can use GET /api/v1/health as its synthetic check and import /api/v1/openapi.json to publish the API to a developer portal.

Settings

ANALYTICS_PUBLIC_API=0 — on — Turns /api/v1 off. Every call answers 503 disabled.
ANALYTICS_API_TOKENS_FILE — — — The scoped service tokens file (name, SHA-256 digest, role per token). Re-read when it changes.
ANALYTICS_API_RATE_PER_MIN — 600 — Requests a minute per credential
ANALYTICS_API_BURST — 100 — Bucket size per credential
ANALYTICS_MCP=0 — on — MCP off
ANALYTICS_MCP_STDIO=0 — on — Remote MCP servers only
ANALYTICS_MCP_ALLOWED_COMMANDS — any — Executables a local MCP server may be started with
ANALYTICS_MCP_MAX_RESULT_KB — 256 — Largest tool result kept
ANALYTICS_MCP_SERVERS_FILE — — — MCP servers delivered by policy (shown as managed)
AI_ALLOW_MCP=0 — — — Ask Greg may never use MCP, whatever the data policy says
Query time limit, result size, admission lanes — as configured — Apply to API queries exactly as to the application's own

Network exposure

On a server installation, publish the backend only through your reverse proxy (TLS, WAF), as the Server installation page describes. The API and MCP add no listener and no port of their own. An API gateway can use GET /api/v1/health as its synthetic check and import /api/v1/openapi.json to publish the API to a developer portal.

Audit

(the request itself) — Every API call — Who, which route, outcome, request id
query.run — Every query through /query, a connection query, a metric or widget query — Connection, kind, SHA-256 of the SQL, row count, duration, outcome — never data
mcp.tool.call — Every MCP tool call from the API, Ask Greg or Settings — Server, tool, outcome, duration, caller, via, SHA-256 of the arguments — never arguments or results
mcp.server.create / update / delete / test / reset — Every change to an MCP server — Who, which server, what changed (secrets never)

Monitoring

/metrics (Prometheus) includes analytics_http_requests_total{route="/api/v1/…"}, the admission series, and analytics_mcp_calls_total, analytics_mcp_call_duration_seconds, analytics_mcp_circuit_open and analytics_mcp_calls_in_flight per server. Alert on analytics_mcp_circuit_open > 0 for a dependency that has gone away, and on a rising share of 429 or 503 answers for a client that needs a bigger budget.

Troubleshooting

401 unauthorized — No credential, a token whose digest is not in the tokens file, or an expired Entra token. GET /api/v1/me with the same header shows what the server sees.
403 forbidden on a query — The role or an object grant does not cover that table, connection or dashboard. The reason field names which.
422 read_only_sql — The statement writes, holds more than one statement, or reads a file or URL. Run one SELECT or WITH at a time.
400 bad_request with field: cursor — The cursor was sent with a different statement, project or page size. Start again without it.
429 rate_limited — Wait for Retry-After. If it happens in normal running, ask for a higher ANALYTICS_API_RATE_PER_MIN or give the job its own token.
could not start "npx" — Node.js is not on the PATH of the account the backend runs as, or npx is not in ANALYTICS_MCP_ALLOWED_COMMANDS.
the MCP server process exited … server said: … — Read the server's last lines in the Test result — usually a missing variable or a wrong password. For BigQuery, "Invalid JWT Signature" means the service-account key was revoked: create a new key.
MCP server answered HTTP 401 — check the credential — Atlassian API-token sign-in is not enabled for the organisation, or the header is the wrong kind (Basic for a person, Bearer for a service account).
it is a private address and this server only reaches public hosts — Turn on Allow private network for a server inside the company network.
… is failing; calls are paused for N s — The circuit is open. Fix the cause, then press Reset.
A tool is listed but cannot be called — The refusal names the reason: not on the allow-list, not matching the pattern, or a write tool on a read-only server.
Ask Greg does not mention MCP — One of the two switches is off, AI_ALLOW_MCP=0 is set, or the server is disabled or failing.

Glossary terms on this page

KPI dashboard: definition

ATX Institute on LinkedIn

This site needs JavaScript for the full experience. Every page above is reachable without it.