Skip to main content

JupiterOne AI Integration (MCP Server)

The JupiterOne Model Context Protocol (MCP) Server enables AI assistants like Claude (on claude.ai and Claude Desktop), Claude Code, Cursor, and Amazon Kiro to interact directly with your JupiterOne account using natural language.

Prerequisites​

  • Active JupiterOne account with API access
  • JupiterOne API key and account ID
  • Node.js version 20 or higher (for local server only)
  • AI assistant with MCP support (Claude on claude.ai, Claude Desktop, Claude Code, Cursor IDE, ChatGPT, GitHub Copilot, Continue.dev, Cline, Devin Desktop (formerly Windsurf), Amazon Kiro, etc.)

Installation Methods​

Install from the Claude connector directory (easiest)​

JupiterOne is published in the Claude connector directory. If you use Claude, this is the fastest path — there is no JSON to edit and no URL to construct.

  1. Open claude.ai/directory/jupiterone.
  2. Click Connect and choose your JupiterOne region.
  3. Sign in to JupiterOne, then approve the consent screen — it lists what the connector will be allowed to do before anything is granted.

The directory connector uses JupiterOne's hosted remote server, so it requires no local installation and stays on the current release automatically.

Working across several accounts

The directory connector is not tied to one account. If your sign-in can reach more than one, ask Claude to "list my JupiterOne accounts" — every tool acts on one account per call, and list-accounts returns each account you can use along with its accountId.

Have an AI set this up for you​

If you'd rather not edit JSON by hand, copy the prompt below and paste it into your AI assistant. It will ask for the credentials it needs and walk you through the install.

Preview the prompt

Help me install the JupiterOne MCP server in this client. The setup docs are at https://docs.jupiterone.io/integrations/jupiterone-mcp-server.

  1. Ask whether I want the remote (OAuth, recommended) or local (API key) deployment.
  2. If local, ask me for my JupiterOne API key and account ID. My account ID can be found at https://docs.jupiterone.io/features/admin/admin-settings#account-management — this is the account ID, not the vanity domain.
  3. Show me the JSON to add to your MCP config file. If a config already exists, preserve existing servers and merge mine in.
  4. Tell me how to restart and verify the server is connected.

Manual setup​

The JupiterOne MCP Server can be configured in two ways:

Use JupiterOne's hosted MCP server without local installation:

  • URL Format: https://your-account-id-here.mcp.<REGION>.jupiterone.io/mcp
  • Example: https://j1dev.mcp.us.jupiterone.io/mcp
  • Authentication: OAuth-based authentication with JupiterOne login

Replace <REGION> with us or eu based on your JupiterOne instance. The examples in this guide use us.

Remote Server Benefits

The remote HTTP server option:

  • Requires no local installation
  • Handles authentication through JupiterOne's OAuth flow
  • Automatically stays up-to-date with the latest features
  • Works across different machines without setup

Option 2: Local Server (stdio)​

Install and run the MCP server locally using npx:

npx @jupiterone/jupiterone-mcp

Or install globally for repeated use:

npm install -g @jupiterone/jupiterone-mcp

Configuration​

Get Your Credentials​

For Remote Server (Option 1)​

  • Account ID: Found in Account Management
  • Region: Your JupiterOne instance region (e.g., us, eu)

For Local Server (Option 2)​

  1. API Key: Navigate to Settings → User API Tokens in JupiterOne and create a new API key
  2. Account ID: Found in Account Management or by running: find jupiterone_account as x return x.accountId
AI Access
  • Local Server: Uses API key authentication and runs within the context of the user, respecting RBAC configuration
  • Remote Server: Uses OAuth authentication through JupiterOne login, automatically applying your user permissions

AI Platform Setup​

Configuration file location:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
Local server​

Edit the configuration file above and add:

Local Server Configuration:

{
  "mcpServers": {
    "jupiterone": {
      "command": "npx",
      "args": ["-y", "@jupiterone/jupiterone-mcp"],
      "env": {
        "JUPITERONE_API_KEY": "your-api-key-here",
        "JUPITERONE_ACCOUNT_ID": "your-account-id-here"
      }
    }
  }
}

Restart Claude Desktop.

Remote server​

In the Claude Desktop App:

  1. Navigate to Settings → Connectors.
  2. Click Add custom connector at the bottom of the section.
  3. Set the title to JupiterOne and the URL to https://your-account-id-here.mcp.us.jupiterone.io/mcp.
  4. Click Add and complete the OAuth sign-in.

Verify Installation​

Once configured, test the connection by asking your AI assistant:

"List my JupiterOne integrations"

A successful response confirms the MCP server is connected and authenticated. If you receive an error or no response, see Troubleshooting.

What You Can Do​

The MCP server provides 29 tools spanning query execution, alert monitoring, rules management, dashboard management, integration monitoring, and account discovery. Ask your AI assistant questions in natural language — it selects the right tool and, when a query is needed, writes the J1QL for you.

Prompt Templates by Use Case​

Copy any prompt below and paste it into your AI assistant. Where a prompt produces a J1QL query, the query is shown so you can learn the syntax or adapt it.

PromptJ1QL the AI generates
"How many cloud instances do I have, broken down by provider?"Find Host with _integrationType != undefined as h return h._integrationType as Provider, count(h) as Total
"List all data stores that are not encrypted"Find DataStore with encrypted != true
"Show me all resources without a data classification tag"Find (Host|DataStore) with classification = undefined
"Which S3 buckets are publicly accessible?"Find aws_s3_bucket with classification = 'Public' OR bucketPolicy.public = true
"Find all hosts that have not been scanned in the last 30 days"Find Host that !has Assessment with _createdOn > date.now-30days

For the full J1QL language reference, including traversals, aggregations, and filtering, see the J1QL documentation.

Available Tools​

The MCP server exposes the following tools. Your AI assistant selects the right tool automatically based on your question.

Query Execution
ToolDescription
execute-j1ql-queryExecute any J1QL query. Supports variables, cursor-based pagination, deleted entity inclusion, scope filters, and query flags.
get-query-resultsRetrieve results of a long-running query. Use when execute-j1ql-query returns status: "IN_PROGRESS" with a resultsUrl.
Alert Monitoring
ToolDescription
get-active-alertsList currently active alerts, with optional limit (1–1000).
Rules Management
ToolDescription
list-rulesList all rules in the account, with optional limit.
get-rule-detailsGet full details of a specific rule by ID.
create-inline-question-ruleCreate a new inline question-based rule with queries, operations, and actions.
update-inline-question-ruleUpdate an existing inline question rule.
delete-ruleDelete an alert rule. Irreversible, and it does not dismiss alerts the rule already raised.
evaluate-ruleTrigger on-demand evaluation of a specific rule.
list-rule-evaluationsGet historical evaluation data for a rule, with optional time range filtering.
get-rule-evaluation-detailsGet detailed evaluation results including query output, condition results, and action results.
get-raw-data-download-urlGet a download URL for raw evaluation data.
get-rule-evaluation-query-resultsGet the actual query results from a rule evaluation.
Dashboard Management
ToolDescription
get-dashboardsList all dashboards in your account.
create-dashboardCreate a new dashboard.
get-dashboard-detailsGet full dashboard information including widgets and layouts.
update-dashboardUpdate an existing dashboard's layout.
create-dashboard-widgetAdd a widget to a dashboard.
update-dashboard-widgetUpdate an existing widget's query, title, or chart type.
delete-dashboardDelete an entire dashboard and all its widgets.
delete-dashboard-widgetDelete a single widget from a dashboard.
Integration Management
ToolDescription
get-integration-definitionsList available integration types, optionally including configuration fields.
get-integration-instancesList configured integration instances, optionally filtered by definition.
get-integration-jobsList integration jobs filtered by status, instance, or definition.
get-integration-jobGet details for a specific integration job.
get-integration-eventsGet events for a specific integration job, with pagination.
Account Management
ToolDescription
test-connectionTest connectivity and return account information and permissions.
list-accountsList JupiterOne accounts the authenticated user can access, each with its accountId, display name, and mcpUrl — the connector URL that pins that account. Use it to find the right account when a connector points at one you cannot reach.
list-entity-typesDiscover all entity classes and types available in your account.

Known Limitations​

Current Limitations
  • Deletes cover rules and dashboards only: delete-rule, delete-dashboard, and delete-dashboard-widget are the only delete operations. Integrations, entities, and other resources cannot be deleted through the MCP server. Write and delete tools are annotated (readOnlyHint/destructiveHint) so MCP clients can prompt for approval before running them.
  • Deleting a rule does not dismiss its alerts: alerts the rule already raised stay active after the rule is gone, and the rule's configuration cannot be recovered. To stop a rule firing while keeping its configuration and evaluation history, ask for its polling interval to be set to DISABLED instead of deleting it.
API Rate Limits

The MCP server consumes your JupiterOne API rate limit quota. Each operation counts against your API rate limits. Monitor your usage to avoid hitting limits during critical operations.

Troubleshooting​

URL uses your vanity domain instead of your account ID​

The remote server URL must use your account ID, not your vanity domain (the custom subdomain like acme.app.us.jupiterone.io). If you see authentication or "account not found" errors with the remote server, double-check the URL.

Find your account ID in Account Management — it is listed separately from the Vanity URL.

Server does not appear in your client​

  1. Confirm your JSON config is valid (a single trailing comma will cause silent failure).
  2. Restart your AI client. Most clients only load MCP config on startup.
  3. Check the client's MCP log:
    • Claude Desktop: ~/Library/Logs/Claude/mcp*.log (macOS) or %APPDATA%\Claude\logs\mcp*.log (Windows)
    • Cursor: Output panel → "Cursor MCP"
    • VS Code (Copilot/Cline): Output panel → relevant extension
    • Kiro: Output panel → "Kiro - MCP Logs"
    • Claude Code: run /mcp inside the session

npx or command not found errors​

The local server requires Node.js 20+ on your PATH. Run node --version in the same shell your client uses. On macOS, GUI apps may not inherit your shell's PATH; use an absolute path to npx (find it with which npx) in the config.

OAuth flow fails for the remote server​

Sign out of your JupiterOne account in your browser, then retry the OAuth handshake.

A query comes back as status: "IN_PROGRESS"​

This is not an error. Heavy graph traversals can outlive a single tool call, so the query keeps running on the server and the response carries a resultsUrl handle. Your assistant should call get-query-results with that handle to collect the results — it does not need to run the query again.

  • Queries that succeed almost always finish within about 4 minutes.
  • Past roughly 13 minutes a query will not complete. Narrow it — indexed WITH filters, a smaller LIMIT, fewer traversals — and run it again.
  • The handle expires about an hour after the query started. Re-running an identical query within about 5 minutes re-attaches to the same execution instead of starting over.

If your assistant keeps re-issuing execute-j1ql-query instead of using the handle, it restarts the query from scratch each time. Tell it to call get-query-results with the resultsUrl it was given.

A valid query is rejected as a syntax error (local server)​

The local server checks J1QL against a copy of the platform's query grammar that is bundled when the package is published, so syntax mistakes come back instantly instead of costing a round-trip. A significantly out-of-date install can therefore reject syntax that a newer query service would accept.

Update the package first: npx picks up the newest version on each run, and a global install updates with npm install -g @jupiterone/jupiterone-mcp. If you need to bypass the local check in the meantime, set JUPITERONE_SKIP_QUERY_VALIDATION to 1 in your MCP client config — the backend still validates every query.

{
  "mcpServers": {
    "jupiterone": {
      "command": "npx",
      "args": ["-y", "@jupiterone/jupiterone-mcp"],
      "env": {
        "JUPITERONE_API_KEY": "your-api-key-here",
        "JUPITERONE_ACCOUNT_ID": "your-account-id-here",
        "JUPITERONE_SKIP_QUERY_VALIDATION": "1"
      }
    }
  }
}

This applies to the local server only. The remote server always runs the current release, so its grammar cannot fall behind.

Hitting API rate limits​

Each MCP query consumes JupiterOne API quota. See API rate limiting for limits and recommendations.

FAQ​

Data Residency & Processing​

The JupiterOne MCP Server is available in two deployment modes. The local server runs on your machine and uses your API key to fetch data on demand from JupiterOne's cloud — data never passes through any centralized JupiterOne MCP host. The remote HTTP server is hosted by JupiterOne in the same region as your account and authenticates via OAuth; data residency follows the same regional principles as standard JupiterOne API access. In both modes, retrieved data is forwarded to your AI assistant's LLM provider (e.g., Anthropic, OpenAI) per your client's configuration.

LLM Compatibility & Data Handling​

The MCP Server integrates with any AI assistant that supports the Model Context Protocol (MCP), including Claude on claude.ai, Claude Desktop, Claude Code, Cursor IDE, ChatGPT, GitHub Copilot, Continue.dev, Cline, Devin Desktop (formerly Windsurf), and Amazon Kiro. Once the server is running and configured, your assistant can use natural language to request security data, which is fetched from JupiterOne and passed to the LLM for interpretation. This means data such as asset inventories, vulnerability reports, or alert summaries can be included in AI prompts, depending on what you query. It's important to treat this as a form of third-party data sharing—ensure your selected assistant has appropriate enterprise security practices in place.

Privacy, Logging & Data Sharing​

Your API key (local server) or OAuth session (remote server) governs all access, and data is only transmitted in response to your assistant's specific queries. JupiterOne does not store the results of your queries, your query parameters, or action payloads.

For operational monitoring, the remote server records sanitized, non-sensitive usage telemetry — such as which tool ran and whether it succeeded — with query content redacted. The local server keeps this telemetry on your own machine and sends nothing to JupiterOne.

Separately, your AI assistant may log conversations or prompts on its own platform, just as it would during typical usage. To manage exposure, review your LLM provider's data retention and privacy terms, and consider using enterprise or self-hosted models for sensitive environments.

For JupiterOne's formal data-handling commitments — including data collection, retention, storage, and third-party processors — see the Privacy Policy, Data Processing Addendum, and Subprocessors in the Legal & Security Hub. For privacy questions, contact privacy@jupiterone.com.

Access Control & Security Enforcement​

Data access through the MCP Server is governed entirely by the credentials you provide. The local server inherits all access controls from the user role attached to the API key; the remote server inherits them from the OAuth-authenticated user. AI assistants can only retrieve what your account has permission to access. You can further restrict access by scoping the API key, adjusting user roles, or disabling individual MCP tools. You retain full control over when the server runs and what it can access — turning off the server or removing its configuration from your assistant completely disables AI access.

Rate Limits & Quotas​

Every request made through the MCP Server counts against your JupiterOne API rate limit. This includes queries for asset data, alerts, dashboards, or integrations. Frequent use through an AI assistant could impact your rate quota if not monitored. We recommend reviewing your API usage regularly—especially when enabling assistants for broad or high-frequency queries—to avoid service slowdowns.

Deployment, Support & Customer Control​

The JupiterOne MCP Server can be deployed either locally on your machine or accessed through JupiterOne's hosted remote server. The local server runs entirely in your environment with no persistent connections; the remote server connects securely through OAuth authentication and is hosted in the same region as your account. You can disable either at any time by stopping the local process or removing your AI assistant's MCP configuration. For assistance or onboarding, reach out to your CSM or email support@jupiterone.com.

Release notes​

  • What's new in MCP 2.0 — the 2026-07-28 protocol revision, a cacheable tool list, accurate query result schemas, and the Node.js 20 requirement for the local server
  • What's new in MCP 1.0 — the first generally available release: 24 tools, hardened OAuth on the remote server, structured output, and the 1.x point releases that took it to 28 tools

Support​

For technical support or questions, email support@jupiterone.com. Existing customers can also reach their Customer Success Manager or use their standard JupiterOne support channels.

Contents