Documentation / MCP & AI

MCP Server

Nexus embeds a Model Context Protocol server that mirrors its REST surface and is governed by the same RBAC and audit trail, so AI agents act strictly within the connecting identity's permissions, inside your own Azure tenant.

Nexus ships a built-in Model Context Protocol (MCP) server so AI agents — Claude, GitHub Copilot, Claude Code, or any other MCP-capable client — can work with your data through a single, governed interface. The server runs inside your Azure tenant alongside the rest of Nexus and exposes essentially the same operations as the REST API, over the same identity, RBAC, and audit machinery. This page is for engineers and security teams who want to understand exactly what an agent can reach, how those calls are authorized, and what is recorded. If you just want to pair a client, see Connecting AI Agents.

What the MCP server is

The MCP server is part of the per-tenant Nexus image — there is no separate service to deploy and no Stingray-hosted endpoint in the path. It presents the Nexus surface as a set of MCP tools, so an agent can read schemas, run queries and reports, and author and version pipelines without leaving its conversation.

The design principle is deliberate: the MCP server is not a parallel API with its own rules. It is a thin protocol adapter in front of the same request handlers, permission checks, and audit hooks that serve the REST API and the desktop app. A read tool resolves to the same query path a dashboard uses; a save tool commits to the same version-control substrate the web UI writes to. This is what lets us make a strong claim honestly: an agent can do neither more nor less than the identity it connects as.

Transport is standard streamable HTTP — one request per tool call, stateless on the server. There is no long-lived socket to drop, so the connection tolerates container restarts and scale-to-zero without a manual reconnect. (One practical consequence: if the underlying server revision changes mid-session, re-establish the connection before relying on it.)

The governance model (read this first)

Everything below about tools is secondary to one fact: the same RBAC and audit that govern the REST surface govern the MCP surface. An agent is always acting as a concrete Nexus identity — a signed-in user or a registered application principal — and every tool call is authorized against that identity's permissions before it runs.

No anonymous access. A call carries an authenticated identity or it is rejected. There is no unauthenticated tool.
Permission checked per call, per resource. Nexus enforces per-resource scoped grants (on pipelines, reports, bridges, files, sites, tools, roles) in addition to the built-in tenant roles (Reader and Admin) and any custom roles. A read tool requires the read permission for that kind or bridge; a write tool requires the matching write permission; there is no ambient "because it's an agent" elevation.
Agents inherit, never exceed. An agent paired to a Reader identity cannot author or run a pipeline, full stop — the write handlers refuse before touching state. This is the core governance point: the connecting identity is the ceiling.
Credential isolation holds. Bridge credentials resolve for the acting identity. A user-scoped bridge secret can never be resolved on behalf of a different user, and the agent never receives raw data-source credentials at all — it receives the results of tools Nexus runs on its behalf.
Human-only where it matters. Certain sensitive operations (some authoring and restore paths, and operations that mint or manage credentials) are restricted to human sign-ins and reject automation tokens outright.
Everything is recorded. Queries, report runs, and entity changes are written to the audit trail; entity edits are additionally version-controlled with full diff and restore. Because Nexus runs in your subscription, that record — and the data itself — never leaves your tenant.

For the underlying model, see Roles & RBAC, Execution Roles, and Audit & Telemetry.

Tool categories

The tool catalog mirrors the platform's capabilities. It falls into a handful of clear groups.

Discovery and querying

The starting point for almost every agent session.

Tool	Purpose
`list_bridges`	Enumerate the configured data sources (PostgreSQL, MySQL, SQL Server, NetSuite, QuickBooks, Monday, the internal workspace, generic HTTP/REST, and more) the caller is allowed to see.
`discover_schema`	Inspect tables, fields, and types for a bridge before querying it. Available on every adapter.
`query_data`	Run a read query against a bridge, scoped to the caller's grants and subject to the adapter's declared pushdown/capability model.

The intended flow is discovery-first: list_bridges → discover_schema on the one you need → query_data. Filtering, ordering, and aggregation are governed by each adapter's capability model — where an operator can't be pushed down, the engine evaluates it in memory against a bounded row budget rather than returning silently wrong results.

Reports

Tool	Purpose
`execute_report`	Run a saved report by id with parameters. Returns result rows as structured JSON alongside an execution log and pushdown diagnostics, so an agent can see not just the answer but how it was produced.

Saved reports are the reliable way to give an agent a curated, parameterized query surface rather than open-ended SQL. See Reports.

Entity authoring (pipelines, reports, sites, skills)

Authoring is handled by one unified set of verbs that works across every versioned entity kind — pipeline, report, site, and skill:

Tool	Purpose
`save`	Create or update — validates, then auto-commits a new revision
`get`	Read the live revision or any past revision
`validate`	Check content without saving
`list`	List entities of a kind
`delete`	Remove an entity (recorded as a commit)
`history`	View the commit log for an entity
`diff`	Compare two revisions
`restore`	Roll an entity back to an earlier revision
`status`	Repository head and per-kind counts

Every save is validated and committed to a built-in version-control substrate (a per-tenant git repository on Azure Files), so authoring through an agent is fully auditable and reversible. Pipelines are Python modules — each defines async def run(ctx) and uses the sandboxed ctx SDK (ctx.adapters, ctx.secrets, ctx.http, ctx.logger, ctx.workspace, ctx.files). The agent writes the Python source directly through save.

# Example pipeline source saved via the MCP entity surface
async def run(ctx):
    customers = ctx.adapters.mssql.query("SELECT id, name FROM customers")
    ctx.logger.info(f"fetched {len(customers)} customers")
    return {"count": len(customers)}

Because pipeline source executes on the server, saving a pipeline requires an elevated write permission and, for the sensitive paths, a human sign-in. See the Pipeline SDK for the full ctx contract and the sandbox model for what the compiler strips (exec/eval, file I/O, unrestricted network) at the AST level.

Pipeline execution and monitoring

Tool	Purpose
`execute_pipeline`	Run a saved pipeline now, as the acting identity (or under a pinned execution role).
`test_pipeline`	Validate and dry-run pipeline source before committing it.
run-history tools	Inspect run status, structured logs, diagnostics, and the complete traceback on failure.

Runs go through the same durable queue, per-run timeout, and concurrency controls as any other execution — the agent does not get a fast path around them. See Pipeline monitoring.

Administrative surface (files, secrets, roles, grants)

For identities that hold the right permissions, the MCP surface also exposes the administrative operations of the platform:

Files — create, read, list, and remove tenant files and file references.
Secrets — add, list, and delete named secrets. Secret values are write-only through the surface: an agent can set or rotate a secret and reference it by name, but the surface does not read plaintext back out. See Secrets.
Roles and grants — create and list roles, and create, list, and delete per-resource grants and role assignments; inspect a principal's effective permissions.
Bridges and connectors — manage connection definitions and connectors, subject to the same admin gating.

These are the operations that mint or manage credentials and access, so they are the most tightly gated: admin-level permission plus, for the credential-bearing paths, a human sign-in. An automation token cannot silently escalate itself.

How the MCP server is reached

There are two supported paths, and both are identity-bound — neither exposes an unauthenticated endpoint.

Desktop app + local proxy (recommended). The Nexus desktop app hosts a loopback proxy on your machine. An MCP client points at that proxy; the proxy attaches your signed-in identity, so no token lives in the client's configuration. Pairing is a one-time, human-approved step; the resulting credential is stored in the OS keychain and never displayed. This is the path most teams use and is covered step-by-step in Connecting AI Agents.

Remote MCP (direct). The server also exposes /mcp directly for clients that connect without the desktop proxy. This path is identity-bound as well: access is authenticated either through a browser-linked user OAuth session or a scoped static token (a run-as-me personal token or a registered application principal). There is no default anonymous remote access. Which path a tenant enables is an administrative choice.

Limits and honest boundaries

The agent is bounded by the identity, not by the tool list. Publishing the full catalog does not widen access — a tool the identity lacks permission for simply fails closed.
No raw credentials cross the boundary. The agent receives tool results, never data-source secrets or a standing DB connection.
Pushdown is per-adapter. Query performance and which filters/aggregations run at the source depend on the adapter; the engine falls back to in-memory evaluation (bounded) rather than returning wrong answers. See the connector capability model.
Sessions are stateless per call. If the server revision changes, reconnect before relying on the session.
Tokens are sensitive. Pairing/remote credentials are never printed by Nexus; if one lands in a log or transcript, revoke it. Treat any leaked token as compromised.