Skip to main content

MCP Integration

Connect Claude, ChatGPT, Microsoft Copilot or another MCP-capable assistant to Nexatron so it can answer questions from your governed data inside a conversation.

What is MCP?​

The Model Context Protocol (MCP) is an open standard that lets AI assistants call external tools. When you connect Nexatron as an MCP server, the assistant can ask questions in your own words, browse approved metrics and list your sources, with the same permissions you have in Nexatron.

Two ways to connect​

Nexatron offers two MCP surfaces. They expose different tools, so check which one you are using before you follow an example.

Hosted MCP server (recommended)Local stdio package
Where it runsNexatron's serversYour machine, started by the assistant
Addresshttps://api.nexatron.io/api/v1/mcpuvx nexatron-mcp
Sign-inOAuth 2.1 with your Nexatron identityA Nexatron API key
Tools7 analytics tools, plus 3 action tools when allowed12 tools from the v1 surface
SetupNo installPython and uv on your machine

Hosted MCP server​

Connect any MCP client that supports remote servers to:

https://api.nexatron.io/api/v1/mcp

The server uses the Streamable HTTP transport and OAuth 2.1 with PKCE. Clients that support dynamic client registration register themselves when you first connect. Setup guides for specific assistants:

  • Claude: add Nexatron from Claude's connector directory.
  • ChatGPT: add a custom MCP connector, where your ChatGPT workspace allows it.
  • Microsoft 365 Copilot: use the declarative agent or add Nexatron as a tool in Copilot Studio.

For the endpoint, scopes, tool annotations and errors in one place, see the MCP reference.

Available tools​

These are the tools the hosted server offers. They are the complete callable catalog; two further tool names are reserved stubs and are not offered.

Analytics tools. Always available to a signed-in connection.

ToolDescription
askAsk a question in your own words. Nexatron answers as the signed-in person, under row-level security and using approved metrics, and returns the rows, the generated query and lineage.
list_sourcesList connected data sources (names and ids) and their health.
list_metricsLists the metric definitions available to you, with trust and source. Listed only when your workspace can run them.
explain_metricReturns a metric's definition: formula, filters, table and the columns it can be grouped by.
query_metricRuns one named metric as you, optionally grouped by columns (group_by is a comma-separated string). A refusal comes back as a typed result and is not charged.
compare_metric_across_sourcesRuns several named metrics one after another (metrics is a comma-separated list) and returns each result, or the reason it was refused. It does not join sources.
auditRead your own audit trail for actions taken through this server.

Action tools. Let an agent propose and run governed changes in a connected system.

ToolDescription
list_actionsList the actions available to you.
dry_runPreview an action's contract and predicted effects without changing anything.
execute_actionRun an action. This changes data in a connected system. High-risk or irreversible actions need a typed confirmation.

Which tools a connection sees depends on two things:

  1. The workspace action setting. The action tools are on by default for each workspace. A workspace administrator can switch them off, and then every connection sees only the analytics tools.
  2. The scopes the connection was granted. With an upcoming update, the tool list follows the granted scopes. A connection that granted only read scopes (for example Claude's default request, mcp:read mcp:query openid offline_access) sees only the analytics tools. The action tools need an actions:* scope as well. Today the list follows the workspace setting alone, and an action call without an actions:* scope is refused.

Queries that span several sources in one question (federation) are on by default for new workspaces. A workspace admin can turn them off.

Examples with the hosted server​

Ask your assistant questions in your own words. It picks the tools.

Ask a question.

"What were our total sales last quarter?"

The assistant calls ask with your question and gets back the answer, the query, the result rows and lineage.

See your sources.

"Which data sources do I have connected in Nexatron?"

The assistant calls list_sources and shows each source with its health.

Browse metrics.

"What metrics are defined in the semantic layer?"

The assistant calls list_metrics, then explain_metric when you ask how one is defined.

Run several metrics together.

"Show revenue and gross margin for this quarter."

The assistant can call compare_metric_across_sources with both metric names to get them in one call.

Follow up.

"Show me revenue by region, then drill into the fastest growing one."

The assistant chains ask calls and keeps the conversation context.

Local stdio package​

The nexatron-mcp package runs on your machine and talks to the Nexatron REST API with an API key. It is for assistants that start local MCP servers from a config file, such as Claude Desktop. It exposes the older v1 tool set, not the hosted tools above.

Configure Claude Desktop​

Add the server to your Claude Desktop configuration file.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "nexatron": {
      "command": "uvx",
      "args": ["nexatron-mcp"],
      "env": {
        "NEXATRON_API_KEY": "nxa_your_api_key_here",
        "NEXATRON_URL": "https://api.nexatron.io/api/v1"
      }
    }
  }
}

Restart Claude Desktop after saving the file. Create the API key under API tokens.

Self-hosted alternative​

If you run a self-hosted Nexatron instance, point the package at your API:

{
  "mcpServers": {
    "nexatron": {
      "command": "uvx",
      "args": ["nexatron-mcp"],
      "env": {
        "NEXATRON_API_KEY": "nxa_your_api_key_here",
        "NEXATRON_URL": "http://localhost:8000/api/v1"
      }
    }
  }
}

Local package tools​

ToolDescription
queryAsk a question in your own words; returns the answer, the generated query and a result preview.
list_connectionsList all configured data source connections.
get_schemaFetch the tables, columns and types for a connection.
test_connectionCheck connectivity and latency for a connection.
detect_schema_driftReport schema changes since the last discovery run.
list_metricsList semantic-layer metrics with their trust labels.
list_viewsList logical views defined in the semantic layer.
search_knowledge_baseSearch ingested documents.
list_conversationsList your recent query conversations.
get_reportFetch a saved report by id.
get_credit_balanceReturn the workspace's remaining query credits.
whoamiReturn the signed-in user and workspace.

These are v1 tool names. The hosted server does not offer them; use ask, list_sources and the other hosted tools there.

Examples with the local package​

"What database connections do I have set up in Nexatron?"

The assistant calls list_connections and lists your connections with their status.

"Show me the orders table schema in the production database."

The assistant calls get_schema for that connection.

Troubleshooting​

Hosted: sign-in fails or waits for approval. A workspace administrator may need to approve the assistant first. See workspace approval.

Hosted: action tools missing. Check whether the workspace has actions switched off and which scopes the connection was granted.

Local: tools not appearing. Fully quit and restart Claude Desktop, not just the window. Check that the config JSON is valid.

Local: authentication errors. Check that the API key is correct and has not expired. Create a new one under API tokens.

Local: connection timeouts. On a self-hosted instance, confirm that NEXATRON_URL is reachable from your machine.

Permission errors. Both surfaces act as you. An API key inherits the permissions of the user who created it, and an OAuth connection can never do more than your Nexatron role allows.

Next steps​

Last updated on