Documentation / MCP & AI

Connecting AI Agents

Pair Claude, GitHub Copilot, or any MCP client to your Nexus instance to give an AI assistant governed, least-privilege, fully audited access to your live business systems — every call running as the connecting identity, inside your own Azure tenant.

Nexus exposes a built-in Model Context Protocol (MCP) server, so any MCP-capable AI client — Claude, Claude Code, GitHub Copilot, or your own agent — can query your data, run reports, and operate pipelines through the same permissions and audit trail as a human user. This page explains how an agent connects, what it can safely do once connected, and why that connection stays inside your control. For the tool catalog and the governance model in depth, see MCP Server.

What you get, and for whom

Once paired, the AI client sees the Nexus tool surface as a set of nexus tools: discovering schemas, querying configured data sources ("bridges"), running saved reports, and — for identities that hold the permission — authoring and running pipelines, reports, and sites. The agent never gets raw database credentials or a standing connection to your systems. Every call is brokered by Nexus, authorized against the connecting identity's role and grants, and recorded.

This is for teams who want an AI assistant to do real work against real, governed data — finance reconciliations, operational reporting, cross-system data integration — without copying that data into a third-party model or handing out direct database access. The agent works through Nexus; Nexus works inside your Azure subscription; the data stays in your boundary.

The core idea: the agent runs as the connecting identity

The single most important thing to understand is the run-as-the-connecting-identity model. An agent is never a special principal with its own powers. When you pair a client, it is bound to a concrete Nexus identity — normally your signed-in user, optionally a scoped application principal — and every tool call executes with exactly that identity's permissions.

The agent's reach is the identity's reach. Never more, and never less.
Role checks and per-resource grants are evaluated per request, the same as a human session — not once at connect time.
Bridge credentials resolve for the acting identity only. A user's credentials can never be resolved on behalf of a different user, and the agent itself never sees them.

This is what makes it safe to let an assistant loose on live systems: the blast radius is defined entirely by the account you paired it under. Pair it under a Reader and it can read; pair it under an Admin and it can author. There is no "agent mode" that widens that.

How the connection works

The agent does not talk to your data sources directly. It talks to Nexus over MCP, and Nexus enforces access on every request.

AI client (Claude / Copilot / your agent)
   │  MCP over Streamable HTTP (one request per tool call)
   ▼
Nexus desktop app  ──  loopback proxy on your machine
   │  attaches your signed-in identity; no token in the client config
   ▼
Nexus  /mcp  ──  authenticates, checks RBAC, runs the tool, writes an audit record
   ▼
Your configured bridges (databases, SaaS APIs) inside your Azure tenant

The transport is stateless Streamable HTTP: one request is opened per tool call, so there is no fragile long-lived session to drop. The connection survives desktop restarts and server scale-to-zero and stays responsive.

Identity is injected by the desktop proxy, so the token never lives in the agent's configuration file. (A direct remote path to /mcp also exists for clients that don't use the desktop proxy; it is identity-bound too — see MCP Server → How the MCP server is reached.)

Pairing an agent

Connecting a client is a one-time approval, modeled on device pairing so a human always authorizes the link.

Start the Nexus desktop app. It hosts the local loopback proxy that injects your signed-in identity.
Initiate pairing from the client side. The client requests a connection; Nexus issues a short-lived numeric pairing code.
Approve the code in the desktop app under Connected apps. You see the requesting app's name before you approve, so you know what you're authorizing.
The client receives its credential once and stores it securely (on macOS, in the system keychain). From then on the agent connects automatically.

Pairings are persistent and identified by a stable client ID, so re-pairing the same client rotates its credential rather than accumulating stale ones. You can revoke any connected app at any time from Connected apps → Revoke, which immediately invalidates that agent's access. Nexus never prints or echoes the credential; treat any pairing token that ends up in a log or transcript as compromised and revoke it.

What an agent can safely do

Because the agent runs as your identity, "what it can do" is just "what you can do," filtered per request. Concretely:

Read-side work — schema discovery, ad-hoc queries, and running saved reports — is available to any identity with the corresponding read permission or grant.
Write-side work — creating or running pipelines, editing reports, publishing sites, managing secrets or grants — requires the matching write/admin permission. An agent paired under an account that lacks it simply cannot perform the action; the handler fails closed.
Sensitive operations — some authoring/restore paths and any operation that mints or manages credentials — require a human sign-in and reject automation tokens.

The safe pattern most teams adopt is to pair the agent under a purpose-scoped identity: give it exactly the bridges, reports, and pipelines it needs via per-resource grants, and nothing else. See Roles & RBAC and Execution Roles for how to scope that precisely, including pinning a curated role to a pipeline with no standing elevation.

Why one UQL operating pattern helps agents

Nexus deliberately gives agents one consistent operating pattern rather than a different shape per system, and that consistency is what makes an assistant reliable across a heterogeneous estate:

One discovery contract. discover_schema works the same on PostgreSQL, NetSuite, Monday, QuickBooks, and the internal workspace. The agent learns one way to find out what's queryable.
One query surface. UQL presents a single query model across every bridge; the agent doesn't need per-vendor SQL dialect knowledge to ask a question. Each adapter declares its own capability/pushdown model, and where an operator can't be pushed to the source, the engine evaluates it in memory (bounded) rather than returning silently wrong results — so an agent's query degrades honestly instead of lying.
One authoring surface. The same verbs (save / get / validate / history / diff / restore) apply to pipelines, reports, sites, and skills. An agent that learns to author one kind can author them all, and every change is versioned.

The payoff: an agent can reason about your whole environment with one mental model, which means fewer wrong turns and a much smaller surface for it to misuse. See UQL Introduction.

Guardrails

The connection is safe by construction, not by convention:

RBAC on every call. Authorization is evaluated per request against the connecting identity's roles and per-resource grants. There is no ambient agent privilege.
No credential exposure. The agent holds a pairing token for the proxy, not your data-source credentials. Bridge secrets stay in your tenant's Key Vault and are never handed to the client.
Identity preserved end to end. Calls reach Nexus as the actual signed-in user, so role checks and resource grants apply exactly as in a human session.
Capability model, not raw access. The agent invokes governed tools; it does not get a raw connection it can point anywhere. Writes are additionally gated per adapter (read-only collections, blocked views, and formula columns are refused).
Everything is recorded. Tool calls, pipeline runs, and their results are auditable through Nexus; you can inspect a run's status, diagnostics, logs, and — on failure — the complete traceback after the fact. See Audit & Telemetry.
Runs in your tenant. Nexus is deployed inside your own Azure subscription. Data accessed by the agent stays within your boundary; the AI client receives only the specific results of the tools it calls.

A typical agent session

A connected agent follows the same discovery-first pattern a person would:

list_bridges — see which data sources are configured and available to this identity.
discover_schema — inspect tables and fields on a bridge before querying.
query_data or execute_report — pull the records it needs, bounded by your permissions and the adapter's pushdown model.
(With write permission) author or run a pipeline — a Python module defining async def run(ctx) that reads bridges, secrets, and HTTP through the supplied sandboxed context, committed to version control on save.

To give the agent your team's conventions and runbooks so it doesn't have to guess, publish Skills — versioned markdown playbooks it pulls on demand.

Revoking access

To disconnect an agent, open Connected apps in the desktop app and revoke the pairing. The credential stops validating immediately, and the agent loses all access until a human approves a new pairing. Because pairings are keyed to a stable client ID, revocation is precise — you cut one agent without touching the others.