--- title: "Nucleus MCP Server" slug: "nucleus-mcp-server" updated: 2026-11-05T15:56:37Z published: 2026-11-05T15:56:37Z canonical: "help.nucleussec.com/nucleus-mcp-server" --- > ## Documentation Index > Fetch the complete documentation index at: https://help.nucleussec.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. | **Client** | **Status** | **Notes** | | --- | --- | --- | | Claude Code (CLI) | **Verified** | Setup in **Verified Client Configurations** below. | | GitHub Copilot in VS Code (Agent mode) | **Verified** | Setup in **Verified Client Configurations** below. | | GitHub Copilot CLI | **Verified** | Requires a GitHub account with an active Copilot license. Setup in **Verified Client Configurations** below. | | ChatGPT desktop app (custom MCP) | **Verified** | Must use the **Streamable HTTP** server type, not STDIO. Setup in **Verified Client Configurations** below. | | Microsoft Copilot Studio | **Verified** | Use OAuth 2.0 with **Dynamic (with discovery)**. Setup in **Verified Client Configurations** below. | | Kiro (CLI) | **Verified** | Setup in **Verified Client Configurations** below. | | Kiro (Desktop) | **Verified** | Setup in **Verified Client Configurations** below. | | KiroCrew (Desktop) | **Verified** | Sign-in is approved in a chat session. Setup in **Verified Client Configurations** below. | | Claude web / Claude Desktop / Claude Enterprise connectors | **Verified** | Add as a custom connector using the MCP URL. On Claude Team and Enterprise plans, only an organization owner can add a custom connector. | 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: ```bash claude mcp add --transport http nucleus https://.nucleussec.com/nucleus/mcp ``` 1. In Claude Code, run `/mcp`, select **nucleus**, and choose to authenticate. 2. Sign in to Nucleus in the browser and click **Accept**. 3. 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`): ```json {  "servers": {    "nucleus": {      "type": "http",      "url": "https://.nucleussec.com/nucleus/mcp"    }  } } ``` 1. Start the server, then choose **Authenticate**. VS Code asks "Do you want Code to open the external website?" - choose **Open**. 2. Sign in to Nucleus in the browser and click **Accept**. 3. 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`): ```bash kiro-cli mcp add --name nucleus --url https://.nucleussec.com/nucleus/mcp --scope global ``` 1. Start Kiro CLI. When it reports that the server requires OAuth, choose to authenticate. 2. Sign in to Nucleus in the browser and click **Accept**. 3. 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`): ```json {  "mcpServers": {    "nucleus": {      "url": "https://.nucleussec.com/nucleus/mcp"    }  } } ``` 1. In the **MCP Servers** panel, choose **Authenticate** on the nucleus server. When asked, allow Kiro to open the external website. 2. Sign in to Nucleus in the browser and click **Accept**. 3. The server shows its tools once authenticated. ### **KiroCrew (Desktop)** 1. Add the server to the KiroCrew MCP config (`~/.kiro/crew/mcp.json`): ```json {  "mcpServers": {    "nucleus": {      "url": "https://.nucleussec.com/nucleus/mcp"    }  } } ``` 1. On the **MCP Servers** dashboard, choose **Apply & Restart** so the change takes effect. 2. Open a chat, start a new session, and send a message that uses Nucleus. KiroCrew prompts you to approve the sign-in in chat. 3. 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** | **What you see** | **Likely cause** | **What to do** | | --- | --- | --- | | 403 when you click Accept | The user does not have both API Access and MCP Server Access on any project. | Ask an administrator to grant both permissions on at least one project. | | 403 on a tool call for a specific project | The user lacks API Access or MCP Server Access on that project. | Ask an administrator to grant both permissions on that project. | | Tools worked, then stopped | The user no longer has both permissions on any project, which revokes active sessions. | Restore the permission and sign in again. | | "Missing Authorization header" on /nucleus/mcp | The OAuth sign-in did not complete. | Complete the add-server and sign-in steps above. | | HTTP 405 | Client is set to SSE transport. | Configure HTTP / Streamable HTTP transport. | | ChatGPT desktop: server added but no auth prompt and no tools | The server type was left on STDIO, so the app tried to run the URL as a local command. | Edit the server and set the type to **Streamable HTTP**, then authenticate. | | Registration rejected: "redirect_uris[0] must be a valid https:// URL or a loopback http:// URL" | The client uses a custom callback scheme (such as `vscode://`) or a non-loopback http callback. | Use a client that uses an https or loopback http callback. If the client cannot, it is not able to connect. | | Client shows "Authentication required" / "Unauthorized" but no error | The server is reachable but you have not completed the browser sign-in yet. | Choose Authenticate (or send a message in chat, for KiroCrew) and complete the Accept step. | | Very large or truncated project list | get_projects returns every project with full detail. | Ask about a specific project, or use NQL. | --- ## **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](https://file+.vscode-resource.vscode-cdn.net/v1/docs/users-roles-and-permissions) for more information on how roles work in Nucleus.