Skip to main content

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 URLhttps://api.nexatron.io/api/v1/mcp
TransportStreamable HTTP. Send JSON-RPC 2.0 requests, single or batched, with POST.
GET on the server URLReturns 405 Method Not Allowed. The server is stateless and does not open a server-to-client stream.
Notifications onlyA body that contains only notifications gets 202 Accepted with no body.
Server metadatahttps://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.

LifetimeValue
Authorization code60 seconds
Access tokenOne hour
Refresh token (with offline_access)30 days, replaced each time it is used

Scopes​

ScopeAllows
mcp:readDiscovery: list_sources, list_metrics, explain_metric
mcp:queryDiscovery plus ask, query_metric and compare_metric_across_sources
mcp:metrics:executequery_metric and compare_metric_across_sources
mcp:federationcompare_metric_across_sources
actions:execute_low, actions:execute_medium, actions:execute_highThe action tools. Running an action also needs the tier that matches the action's risk.
openidStandard OpenID Connect sign-in
offline_accessA 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.

ToolTierAnnotationsDescription
askAnalyticsread-onlyAnswers a question in your own words, as the signed-in person under row-level security. Returns rows, the generated query and lineage.
list_sourcesAnalyticsread-onlyLists connected data sources and their health.
list_metricsAnalyticsread-onlyLists the metric definitions available to you, with trust and source. Listed only when your workspace can run them.
explain_metricAnalyticsread-onlyReturns a metric's definition: formula, filters, table and the columns it can be grouped by.
query_metricAnalyticsread-onlyRuns one named metric as you, optionally grouped by columns. A refusal comes back as a typed result and is not charged.
compare_metric_across_sourcesAnalyticsread-onlyRuns several named metrics one after another and returns each result, or the reason it was refused. It does not join sources.
auditAnalyticsread-onlyLists the caller's own recent events on this server: time, type and status. Not question text or which assistant asked.
list_actionsActionread-onlyLists the actions available to the caller.
dry_runActionread-onlyPreviews an action's contract and predicted effects without changing anything.
execute_actionActiondestructiveRuns 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_action returns a 403 error with the reason and dry_run returns a contract whose authorization says no. Neither calls the source.
  • Granted scopes. With an upcoming update, tools/list shows only the tools the connection's scopes allow. A connection with read scopes only (such as mcp:read mcp:query openid offline_access) sees the seven analytics tools. The action tools also need an actions:* 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.

StatusWhen
400The body is not valid JSON (JSON-RPC -32700) or not a JSON-RPC 2.0 request (-32600).
401The token is missing, expired or revoked. The WWW-Authenticate header tells the client where to sign in again.
405GET on the server URL. Use POST.

JSON-RPC errors.

CodeWhen
-32601Unknown method.
-32602Unknown 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.