Nucleus MCP Server

Overview

The Nucleus MCP (Model Context Protocol) Server allows customers to securely connect their AI systems to Nucleus data and workflows. It provides a standardized and secure interface for AI-driven automation, natural language querying, and contextual enrichment across the Nucleus platform - all while maintaining full adherence to existing access control and data governance policies.

Common Use Cases

• Natural Language Queries: Ask questions in plain language (e.g. "Show all critical vulnerabilities in production assets"); the AI client can leverage NQL Metadata and NQL Reference tools to discover what data is available and supported syntax, then translates these questions into NQL queries and runs them through the NQL Query tool. All NQL access remains bound by the user's RBAC/AGAC permissions.

• Automated Alert Enrichment: Integrate MCP with a SIEM or SOAR platform to provide AI-assisted enrichment of alerts.

• Remediation Planning: Generate prioritized remediation strategies based on active findings.

• Executive Summaries: Produce AI-generated reports on vulnerability trends, risk posture, or remediation performance.

• Cross-System Correlation: Use AI to combine Nucleus data with information from other tools for broader context.

Included Tools

The MCP Server provides structured access to key components of the Nucleus platform. These tools allow AI systems to retrieve and summarize information across your security program, including:

• Project Management Tools Retrieve lists of projects or detailed information about individual projects.

• Asset Management Tools Access data about assets, including asset details, findings, associated groups, and related metrics.

• Findings and Vulnerability Management Tools Obtain vulnerability trend information, view findings sorted by risk, and pull current vulnerability metrics.

• Nucleus Query Language (NQL) Tools Query Nucleus data directly using NQL. These tools let an AI client discover what datasets are available, retrieve the full NQL syntax reference, and execute NQL queries against your findings, assets, and related datasets. NQL tools honor the same RBAC and AGAC enforcement described above - no additional access is granted through NQL.

MCP tools will be updated periodically and will be visible in your AI client's connector UI.

Secure Data Access

The AI client signs in as you, so it can only see what you can see in Nucleus. The MCP Server fully respects the Role-Based Access Control (RBAC) and Asset Group Access Control (AGAC) policies defined in your Nucleus environment.

• Authentication: OAuth 2.0 authorization code with PKCE. You sign in to Nucleus in a browser and click Accept. No API key is required.

• Registration: Clients register themselves automatically using OAuth Dynamic Client Registration (DCR). There is no manual setup step and nothing to paste into your client.

• Sessions: The connection stays signed in as long as it is used at least once a month. After a month without use, sign in again.

• RBAC Enforcement: All AI interactions are bound by the same permissions as the authenticated user. If a user cannot access specific features or data in the Nucleus interface, neither can their connected AI client.

• AGAC Enforcement: Asset-based restrictions remain fully enforced through the MCP Server.

• Read-only: The 13 tools retrieve information: projects, assets, findings, vulnerability metrics and trends, and Nucleus Query Language (NQL) queries. They do not change data.

• Endpoint: https://<your-instance>.nucleussec.com/nucleus/mcp

• Transport: Nucleus supports the Streamable HTTP MCP transport. The SSE (Server-Sent Events) transport is not supported - a client that sends Accept: text/event-stream receives HTTP 405. Configure your client for HTTP / streamable-HTTP transport, not SSE.

Initial Setup

Prerequisites

• Two permissions on the user's role for at least one project: API Access and MCP Server Access. If either is missing, the Accept step during sign-in fails with a 403 error. App Admins and Org Admins do not need these permissions.

• Project access: Tools for a specific project require both permissions on that project. The project list and NQL queries return data from all projects the user can access.

• Your instance name, for example nucleus-us12. The MCP URL is https://<your-instance>.nucleussec.com/nucleus/mcp.

• A verified client (see below).

Note:

No API key is needed to connect. If a user no longer has both permissions on any project, their active MCP sessions are revoked and the next tool call fails.

How connection works

1. Add the Nucleus MCP server to your AI client using only the MCP URL https://<your-instance>.nucleussec.com/nucleus/mcp. Choose the HTTP / Streamable HTTP transport.

2. The client registers itself automatically (OAuth Dynamic Client Registration) and starts the sign-in.

3. A browser window opens asking you to sign in to Nucleus. Review the access request and click Accept.

4. The client reports a successful connection. Ask it a question that uses Nucleus data to confirm.

The client discovers the authorization, token and registration endpoints automatically from the MCP URL. There is nothing else to configure.

Verified Clients

The clients below have been verified to connect to the Nucleus MCP server.

Any client that supports remote HTTP MCP servers and OAuth 2.0 with PKCE can in principle connect using just the MCP URL. Clients that use a callback URL other than https:// or loopback http:// (for example a custom scheme such as vscode://) cannot register and are not able to connect.

Verified Client Configurations

In every case you provide only the MCP URL https://<your-instance>.nucleussec.com/nucleus/mcp and complete the browser sign-in. No API key and no client ID are required.

Claude Code (CLI)

1. Add the server:
   

   claude mcp add --transport http nucleus https://<your-instance>.nucleussec.com/nucleus/mcp

2. In Claude Code, run /mcp, select nucleus, and choose to authenticate.

3. Sign in to Nucleus in the browser and click Accept.

4. Test it, for example: "List my Nucleus projects" or "Show the 5 most recent critical findings in project using NQL".

GitHub Copilot (VS Code)

1. Add the server to your MCP config (mcp.json):
   

   {
     "servers": {
       "nucleus": {
         "type": "http",
         "url": "https://<your-instance>.nucleussec.com/nucleus/mcp"
       }
     }
   }

2. Start the server, then choose Authenticate. VS Code asks "Do you want Code to open the external website?" - choose Open.

3. Sign in to Nucleus in the browser and click Accept.

4. Open Copilot Chat in Agent mode and ask a question that uses Nucleus data.

GitHub Copilot CLI

1. You must be signed in to GitHub with an account that has an active Copilot license.

2. Add the server (interactive wizard, or the equivalent config): choose server type HTTP, set the URL to https://<your-instance>.nucleussec.com/nucleus/mcp, and leave any HTTP header / token fields blank.

3. When prompted that OAuth authentication is required, choose to authenticate.

4. Sign in to Nucleus in the browser and click Accept.

5. Ask it to list your Nucleus projects or tools to confirm.

ChatGPT desktop app (custom MCP) / Codex

1. Go to Settings > Plugins > MCPs > Add > Connect to a custom MCP.

2. Set Type to Streamable HTTP (do not leave it on STDIO). Enter the URL https://<your-instance>.nucleussec.com/nucleus/mcp. Leave the bearer-token and header fields blank.

3. Save. On the server entry, choose Authenticate.

4. Sign in to Nucleus in the browser and click Accept.

5. Ask for the available Nucleus tools to confirm.

Microsoft Copilot Studio

1. In your agent, choose Add a tool > MCP > Add MCP server.

2. Set Authentication to OAuth 2.0 and Configuration type to Dynamic (with discovery). Enter the server URL https://<your-instance>.nucleussec.com/nucleus/mcp.

3. Create a new connection. Sign in to Nucleus in the browser and click Accept.

4. Select the connection and add the tool. Ask the agent a question that uses Nucleus data.

Kiro (CLI)

1. Add the server (use --url, not --command):
   

   kiro-cli mcp add --name nucleus --url https://<your-instance>.nucleussec.com/nucleus/mcp --scope global

2. Start Kiro CLI. When it reports that the server requires OAuth, choose to authenticate.

3. Sign in to Nucleus in the browser and click Accept.

4. Ask it to list your Nucleus tools or projects to confirm.

Kiro (Desktop)

1. Add the server to the Kiro MCP config (~/.kiro/settings/mcp.json):
   

   {
     "mcpServers": {
       "nucleus": {
         "url": "https://<your-instance>.nucleussec.com/nucleus/mcp"
       }
     }
   }

2. In the MCP Servers panel, choose Authenticate on the nucleus server. When asked, allow Kiro to open the external website.

3. Sign in to Nucleus in the browser and click Accept.

4. The server shows its tools once authenticated.

KiroCrew (Desktop)

1. Add the server to the KiroCrew MCP config (~/.kiro/crew/mcp.json):
   

   {
     "mcpServers": {
       "nucleus": {
         "url": "https://<your-instance>.nucleussec.com/nucleus/mcp"
       }
     }
   }

2. On the MCP Servers dashboard, choose Apply & Restart so the change takes effect.

3. Open a chat, start a new session, and send a message that uses Nucleus. KiroCrew prompts you to approve the sign-in in chat.

4. Sign in to Nucleus in the browser and click Accept. Re-probe the dashboard to confirm the server is online.

Claude web / Claude Desktop / Claude Enterprise connectors

1. In Claude, add a custom connector and enter the MCP URL https://<your-instance>.nucleussec.com/nucleus/mcp.

2. Complete the browser sign-in and click Accept.

NOTE: On Claude Team and Enterprise plans, only an organization owner can add a custom connector. If the "Add custom connector" option is disabled, ask your Claude organization owner to add it.

Troubleshooting

AI Control and Responsibility

Nucleus provides the MCP Server as a secure integration layer but does not control, monitor, or validate how connected AI systems interpret or process data once it is delivered from Nucleus.

Customers are responsible for:

• Managing and reviewing AI data access scopes outside of Nucleus

• Ensuring compliance with internal governance and external regulations

• Validating AI-generated outputs before using them in production or automation workflows

Nucleus cannot guarantee the accuracy, reliability, or security of outputs from external AI systems.

Dedicated MCP Access Permission

Access to the MCP Server is governed by a dedicated permission within the Nucleus role model.

• MCP access is enabled by default for all out-of-the-box roles in Nucleus.

• MCP will not function if API access is disabled for the user or role.

See Users, Roles & Permissions for more information on how roles work in Nucleus.