MCP reference
This page describes Nexatron's hosted MCP server. For step-by-step setup, see MCP Integration or the guide for your assistant: Claude, ChatGPT or Microsoft 365 Copilot. The local stdio package has a different tool set, listed under Local stdio package.
Endpoint and transport
| Server URL | https://api.nexatron.io/api/v1/mcp |
| Transport | Streamable HTTP. Send JSON-RPC 2.0 requests, single or batched, with POST. |
GET on the server URL | Returns 405 Method Not Allowed. The server is stateless and does not open a server-to-client stream. |
| Notifications only | A body that contains only notifications gets 202 Accepted with no body. |
| Server metadata | https://api.nexatron.io/.well-known/mcp/server.json |
Nexatron's MCP server has no SSE transport. The separate
/api/v1/mcp/stream route streams progress for a legacy query call and is not
an MCP transport.
Authentication
The server uses OAuth 2.1 with the authorization code flow and PKCE (S256). Clients discover the authorization server from these documents:
- Protected resource metadata:
https://api.nexatron.io/.well-known/oauth-protected-resource - Authorization server metadata:
https://api.nexatron.io/.well-known/oauth-authorization-server
Clients can register themselves with dynamic client registration. A request
without a valid token gets 401 Unauthorized with a WWW-Authenticate: Bearer
header that points to the protected resource metadata.
People sign in with their own Nexatron identity. Every tool call runs as that person, with their role, row policies and masking applied. A workspace administrator approves an assistant for the workspace before people can connect it; see workspace approval.
| Lifetime | Value |
|---|---|
| Authorization code | 60 seconds |
| Access token | One hour |
Refresh token (with offline_access) | 30 days, replaced each time it is used |
Scopes
| Scope | Allows |
|---|---|
mcp:read | Discovery: list_sources, list_metrics, explain_metric |
mcp:query | Discovery plus ask, query_metric and compare_metric_across_sources |
mcp:metrics:execute | query_metric and compare_metric_across_sources |
mcp:federation | compare_metric_across_sources |
actions:execute_low, actions:execute_medium, actions:execute_high | The action tools. Running an action also needs the tier that matches the action's risk. |
openid | Standard OpenID Connect sign-in |
offline_access | A refresh token |
audit does not use a scope; it checks the account's own role and returns only
that person's events. Action scopes are never granted by default and need
explicit consent. A scope only narrows what the assistant can do for you; it
never adds to what your Nexatron role allows.
The server also accepts mcp:reports:read, mcp:conversations and
actions:compose_workflow. None of the hosted tools below use them.
With an upcoming update, the 401 challenge names a read-only default,
scope="mcp:read mcp:query openid offline_access", so a client that follows it
requests only read access.
Tools
The hosted server offers ten tools: seven analytics tools and three action
tools. Two more names are registered as stubs (compose_workflow and watch).
They are not offered and cannot be called.
Every tool has a title and annotations derived from whether it reads or
writes. Read tools carry readOnlyHint: true. The write tool carries
readOnlyHint: false and destructiveHint: true, so clients ask before
running it.
| Tool | Tier | Annotations | Description |
|---|---|---|---|
ask | Analytics | read-only | Answers a question in your own words, as the signed-in person under row-level security. Returns rows, the generated query and lineage. |
list_sources | Analytics | read-only | Lists connected data sources and their health. |
list_metrics | Analytics | read-only | Lists the metric definitions available to you, with trust and source. Listed only when your workspace can run them. |
explain_metric | Analytics | read-only | Returns a metric's definition: formula, filters, table and the columns it can be grouped by. |
query_metric | Analytics | read-only | Runs one named metric as you, optionally grouped by columns. A refusal comes back as a typed result and is not charged. |
compare_metric_across_sources | Analytics | read-only | Runs several named metrics one after another and returns each result, or the reason it was refused. It does not join sources. |
audit | Analytics | read-only | Lists the caller's own recent events on this server: time, type and status. Not question text or which assistant asked. |
list_actions | Action | read-only | Lists the actions available to the caller. |
dry_run | Action | read-only | Previews an action's contract and predicted effects without changing anything. |
execute_action | Action | destructive | Runs an action in a connected system. High-risk or irreversible actions need a typed confirmation. |
Which tools a connection sees
- Workspace action setting. The action tools are on by default for each workspace. A workspace administrator can switch them off. When they are off, the action tools are not listed, and a call to one is refused with a message that the action platform is not enabled.
- Write-back on the connection. A workspace administrator turns it on for each
connection (Knowledge, Sources, the connection, Write-back), and it is off
until they do. With it off, or with the connection not turned on for you,
execute_actionreturns a 403 error with the reason anddry_runreturns a contract whose authorization says no. Neither calls the source. - Granted scopes. With an upcoming update,
tools/listshows only the tools the connection's scopes allow. A connection with read scopes only (such asmcp:read mcp:query openid offline_access) sees the seven analytics tools. The action tools also need anactions:*scope. Today the list follows the workspace setting alone; scopes are still checked on every call.
Queries that span several sources in one question (federation) are on by default for new workspaces. A workspace admin can turn them off.
Legacy v1 tools
Older Nexatron MCP clients used v1 tool names such as query,
list_connections, get_schema, get_data_quality and
search_knowledge_base. These are legacy. The hosted server at
/api/v1/mcp does not list them, and new integrations should use the tools
above. The local stdio package still
exposes a v1 tool set.
Errors
HTTP errors.
| Status | When |
|---|---|
400 | The body is not valid JSON (JSON-RPC -32700) or not a JSON-RPC 2.0 request (-32600). |
401 | The token is missing, expired or revoked. The WWW-Authenticate header tells the client where to sign in again. |
405 | GET on the server URL. Use POST. |
JSON-RPC errors.
| Code | When |
|---|---|
-32601 | Unknown method. |
-32602 | Unknown tool name in tools/call. |
Tool errors. Problems with a tool call come back as a normal result with
isError: true and a message the assistant can read. This covers invalid
arguments, a missing scope, the action tools being switched off, a call over the
rate limit, and failures inside the tool.
Rate limits. Tool calls are currently limited to 100 per minute per
workspace. Responses do not include X-RateLimit-* headers. On the REST API a
limited request gets HTTP 429, with a Retry-After header and a
retry_after field only when the server knows the wait; see
rate limits.