Metadata-Version: 2.5
Name: nexatron-mcp
Version: 1.0.3
Summary: Nexatron MCP server — governed enterprise-data access for Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, and any MCP-compatible AI client. Exposes 12 tools (query, list_connections, get_schema, list_metrics, list_views, search_knowledge_base, detect_schema_drift, test_connection, list_conversations, get_report, get_credit_balance, whoami) and 1 resource (nexatron://platform/info) over the Nexatron REST API with per-tenant isolation and cryptographic audit.
Project-URL: Homepage, https://nexatron.io
Project-URL: Documentation, https://docs.nexatron.io
Project-URL: Support, https://nexatron.io/support
Project-URL: MCP quickstart, https://docs.nexatron.io/quickstart/mcp
Author-email: dotSolved Inc <info@nexatron.io>
Maintainer-email: Nexatron Engineering <engineering@nexatron.io>
License: MIT
License-File: LICENSE
Keywords: ai,analytics,bi,business-intelligence,claude,claude-code,claude-desktop,cursor,data,enterprise,mcp,model-context-protocol,natural-language,nexatron,nl-to-sql,semantic-layer,text-to-sql,voice
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: Plugins
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Database
Classifier: Topic :: Office/Business
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27.0
Requires-Dist: mcp<3,>=1.0.0
Requires-Dist: pydantic<3,>=2.0
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == 'dev'
Requires-Dist: mypy>=1.11.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Requires-Dist: tomli>=2.0.0; (python_version < '3.11') and extra == 'dev'
Requires-Dist: twine>=5.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# nexatron-mcp

<!-- mcp-name: io.nexatron/mcp -->

MCP server for [Nexatron](https://nexatron.io). Ask questions about your enterprise data from Claude and other MCP clients.

## Add Nexatron from Claude's connector directory

Nexatron is listed in Claude's connector directory as a Community connector. In Claude,
open the connector directory, search for **Nexatron**, choose **Connect**, and sign in to
your Nexatron workspace. Nothing to install and no API key to copy. A workspace admin
approves the app before members use it.

Setup guide: [docs.nexatron.io/integrations/claude](https://docs.nexatron.io/integrations/claude).

## Two ways to connect

- **Hosted endpoint (recommended):** `https://api.nexatron.io/api/v1/mcp`, Streamable HTTP
  with OAuth 2.1. This is what the Claude directory listing uses, and other remote-capable
  clients (Cursor, VS Code) can add the same URL. It has up to ten tools (seven analytics,
  three action), filtered by workspace entitlement and the scopes you grant. A read-only
  grant sees the seven analytics tools: `ask`, `list_sources`, `list_metrics`,
  `explain_metric`, `query_metric`, `compare_metric_across_sources` (several metrics in one
  call) and `audit`. The action tools are `list_actions`, `dry_run` and `execute_action`.
  See [docs.nexatron.io/quickstart/mcp](https://docs.nexatron.io/quickstart/mcp).
- **Local stdio package (this package):** `uvx nexatron-mcp`, authenticated with an `nxa_`
  API key. A REST-backed set of 12 read-only tools for self-hosted Nexatron instances and
  local use; see [Available tools](#available-tools-local-stdio-package). The two surfaces
  have different tools and are versioned independently.

The rest of this README covers the local stdio package.

## Install

```bash
pip install nexatron-mcp
# or
uvx nexatron-mcp
```

## Setup

### Claude Desktop: manual config

Add this to `claude_desktop_config.json`. On macOS it is at
`~/Library/Application Support/Claude/claude_desktop_config.json`; on Windows,
`%APPDATA%\Claude\claude_desktop_config.json`.

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

Restart Claude Desktop. The Nexatron tools then appear.

### Claude Desktop: local extension bundle (optional)

You can also build an unsigned MCPB bundle of this local package from
[manifest.json](manifest.json). Claude asks for your API key in a masked field, so the
key does not land in a config file on disk. The bundle is local-only: it is not
published, and Claude's connector directory does not accept MCPB bundles. Build it with:

```bash
bash scripts/build-mcpb.sh
```

That writes `dist/nexatron-mcp-<version>.mcpb`; open it with Claude Desktop to install.

### Claude Code

```bash
claude mcp add nexatron \
  --env NEXATRON_API_KEY=nxa_your_key \
  --env NEXATRON_URL=https://api.nexatron.io/api/v1 \
  -- uvx nexatron-mcp
```

Options for `claude` go before `--`; everything after it is the command that starts the server.

### Cursor / VS Code

Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global), or to your VS Code MCP settings:

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

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `NEXATRON_API_KEY` | Yes | (none) | Your Nexatron API key (starts with `nxa_`) |
| `NEXATRON_URL` | No | `https://api.nexatron.io/api/v1` | Nexatron API URL |

## Available tools (local stdio package)

These are the 12 tools the `nexatron-mcp` stdio package exposes against the Nexatron REST API. The hosted endpoint has a different set; see [Two ways to connect](#two-ways-to-connect).

| Tool | Description |
|------|-------------|
| `query` | Ask questions about your data in plain English |
| `list_connections` | See all data source connections |
| `list_metrics` | View certified metrics in the semantic layer |
| `list_views` | View logical views |
| `get_schema` | Explore database schemas |
| `test_connection` | Test data source connectivity |
| `detect_schema_drift` | Find schema changes |
| `search_knowledge_base` | Search uploaded documents (RAG) |
| `list_conversations` | View recent query history |
| `get_report` | Retrieve a saved report |
| `get_credit_balance` | Check remaining query credits |
| `whoami` | Show your user info and organization |

## Example

After setup, ask Claude:

> "Use Nexatron to show me total revenue by product category for Q4"

Claude calls the `query` tool, which sends your question through Nexatron and returns the answer with the generated query and results.

## Local SSE mode (development)

```bash
NEXATRON_API_KEY=nxa_... nexatron-mcp --sse --port 8001
```

This starts a local SSE server on `127.0.0.1:8001` that uses your API key for every request,
so it guards itself:

- Every request needs `Authorization: Bearer <local token>`. Without `NEXATRON_MCP_LOCAL_TOKEN`
  set, a token is generated at start and printed once to your terminal (stderr); set the variable
  to a long random value (24+ characters) to choose your own.
- A browser request from any origin other than the server's own address is refused, and the
  `Host` header must be the server's address (DNS-rebinding protection).
- `--host` other than a loopback address is refused unless you set `NEXATRON_MCP_LOCAL_TOKEN`
  yourself: everyone who has that token acts as you.
- A wildcard `--host` (`0.0.0.0`, `::`) is refused unless you name each address clients use with
  `--allowed-host HOST[:PORT]` (repeatable; the port defaults to `--port`). The `Host` a client
  sends has to match one of them exactly. `--allowed-host` also adds addresses to a specific
  `--host`, such as a DNS name for it. An IPv6 address is written in brackets in client URLs,
  for example `http://[::1]:8001/sse`.

It is for development on your own machine. It is not the hosted remote server; remote clients
should use `https://api.nexatron.io/api/v1/mcp`.

## Development

Nexatron is a commercial product and its source repository is private, so there is no
public clone URL. To work against the package locally, install it from source:

```bash
pip download nexatron-mcp --no-binary :all: --no-deps
tar xf nexatron-mcp-*.tar.gz && cd nexatron-mcp-*
pip install -e .
nexatron-mcp
```

dotSolved customers with a source agreement can contact `ai@nexatron.io` for
repository access.

## Privacy Policy

Full policy: **<https://dotsolved.ai/privacy>**. Summary of how this connector handles data:

**What is collected.** The server sends the question or arguments you pass to a tool, plus
your `NEXATRON_API_KEY`, to the Nexatron instance at `NEXATRON_URL`. It collects nothing
else: no conversation history, no chat transcripts, no files, and no telemetry of its own.
It does not read Claude's memory, conversation summaries, or user files.

**How it is used and stored.** Requests are processed by your Nexatron instance to answer
the question and are recorded in that instance's per-tenant audit trail, which exists so
your own administrators can review who asked what. Query results are returned to the
caller and are not retained by this package, which holds no local database and writes no
data to disk; the API key is read from the environment and kept only in memory for the
life of the process.

**Third-party sharing.** dotSolved does not sell or rent this data. Your Nexatron instance
routes questions to whichever LLM provider that instance is configured to use; on a
bring-your-own-LLM deployment that is your own Azure OpenAI, Bedrock, or Anthropic
contract, and no question transits a dotSolved-default provider. Self-hosted deployments
send nothing to dotSolved at all.

**Retention.** Governed by your Nexatron instance's tenant configuration, which its
administrators control. This package imposes no retention of its own.

**Contact.** Data updates and removals: `privacy@nexatron.io`. General privacy questions,
including requests for a copy of your personal information: `info@nexatron.io`. Security
disclosures: `security@nexatron.io` (see [SECURITY.md](SECURITY.md)). These are the
addresses named in the full policy linked above.

## License

MIT

---

# Release and registry runbook

Publication is a human-authorized operation owned by `nexatron-deploy`. GitHub Actions is
retired, and a merge or tag in this repository never publishes anything.

## 1. PyPI: publish `nexatron-mcp`

The `nexatron-mcp` Python package must be on PyPI before the MCP Registry record that
references it, because the registry checks the package and the `mcp-name` marker in
this README.

### Pre-flight checklist

- [ ] Required gates in `AGENTS.md` pass.
- [ ] The version in `pyproject.toml` matches `server.json` (both fields), `manifest.json`,
      `release/nexatron-mcp-manifest.json` and the pins in `contracts/producer-gate-plan.v1.json`.
      `__version__` is read from installed metadata, so `pyproject.toml` is its only source.
- [ ] `CHANGELOG.md` has an entry for the version being published.

### Release-candidate steps

```bash
cd server
uv build
uv run --with twine twine check dist/*
shasum -a 256 dist/*.whl dist/*.tar.gz
```

Record the source commit, test evidence and SHA-256 digests, then hand the candidate to the
authorized `nexatron-deploy` workflow. Afterwards, verify https://pypi.org/project/nexatron-mcp/.

## 2. Official MCP Registry

The MCP Registry is separate from Claude's connector directory. Source metadata is
`server.json`. The registry needs a new version to change metadata, so bump the version
with every metadata change. After the matching PyPI version is live, the owner republishes
from `server/` with `mcp-publisher login dns` then `mcp-publisher publish`, signed in
with DNS authentication for `nexatron.io` (`mcp-publisher login dns --domain nexatron.io`),
which controls the `io.nexatron` namespace. Never publish under a personal GitHub namespace.
Do not submit a community-server PR to `modelcontextprotocol/servers`.

## 3. Third-party registries (Cursor, Smithery, Glama, mcp.so, PulseMCP)

Follow [listing/SUBMISSION-RUNBOOK.md](listing/SUBMISSION-RUNBOOK.md). The Cursor Directory
uses a web form; its field sheet is [listing/cursor-directory-submission.md](listing/cursor-directory-submission.md).

## 4. Claude's connector directory

Nexatron is **listed** as a Community connector (published 2026-09-27). Manage the listing at
https://claude.ai/directory/manage/nexatron; do not create a new submission. Evidence and
remaining work are in [listing/CLAUDE-DIRECTORY-READINESS.md](listing/CLAUDE-DIRECTORY-READINESS.md).

## 5. npm: `@nexatron/create-mcp` (not published)

The scaffolding CLI in `bootstrap/` is **not published to npm**, so `npx @nexatron/create-mcp`
does not work for users yet. Do not reference it in user-facing copy until it is published.

Pre-flight before a first publish:

- [ ] `cd bootstrap && npm test` passes.
- [ ] The version in `package.json` is correct.
- [ ] `bin.create-nexatron-mcp` points to `./src/index.js`, whose first line is `#!/usr/bin/env node`.
- [ ] `npm pack --dry-run` shows only the intended files.

Publishing needs an npm account with rights to the `@nexatron` scope and is an owner action.

## 6. Status

| Surface | Status | Notes |
|----------|--------|-------|
| PyPI (`nexatron-mcp`) | Published | 1.0.3 is the current version (1.0.0 June 2026, 1.0.1 and 1.0.2 November 2026). |
| MCP Registry (`registry.modelcontextprotocol.io`) | Published | `io.nexatron/mcp` from 1.0.2. The earlier `io.github.sravanmodugula-solved/nexatron-mcp` record (1.0.0, 1.0.1) is deprecated. |
| Claude's connector directory | Listed (Community) | Since 2026-09-27. Manage at https://claude.ai/directory/manage/nexatron |
| `modelcontextprotocol/servers` (legacy list) | N/A | No longer accepts community PRs |
| npm (`@nexatron/create-mcp`) | Not published | See section 5 |

## 7. Hosted endpoint metadata

`https://api.nexatron.io/.well-known/mcp/server.json` is served by `nexatron-api`
(`app/api/well_known.py`), which is authoritative for the hosted endpoint. This repository's
`release/nexatron-mcp-manifest.json` describes the local stdio package (its 12 tools and
`stdio` transport) and does not feed that route.

When the local package's tools, scopes or capabilities change:

1. Update `src/nexatron_mcp/server.py` and `release/nexatron-mcp-manifest.json`.
2. Bump the version everywhere listed in the PyPI pre-flight checklist.
3. Add a CHANGELOG entry.
