Using the Stellar Cyber MCP Server

This feature is available in Stellar Cyber 6.5.0 as part of the Early Access Program. Capabilities and behavior might change before general availability.

Overview

Requirements

Setup

Verify the Connection

How Authentication Works

Permissions and Privilege Model

Security Best Practices

Overview

The Stellar Cyber MCP Server lets you connect an AI client to the Stellar Cyber Platform and interact with security operations data programmatically through the Model Context Protocol (MCP). It acts as a bridge between an MCP-compatible AI client—such as Claude Code—and the Stellar Cyber Public API, letting the AI client help you manage security cases through natural language.

With the MCP server, you can use an AI client to retrieve case information, review investigation context, examine related alerts and observables, and update selected case fields. This approach extends case review and case-handling workflows into an MCP-compatible client without requiring a custom integration for each action.

In the current Early Access Program release, the available capabilities focus on case management: reading case and alert data and making limited updates to existing cases. Support for additional features is planned for future releases.

Requirements

To use the Stellar Cyber MCP Server, you need the following:

Access to a Stellar Cyber instance running a version with MCP support enabled.
The MCP server URL for your Stellar Cyber instance.
A valid Stellar Cyber API key. The API key functions as a long-lived refresh token and is used to obtain shortlived access tokens.
An AI client that can connect to an MCP server, such as the Claude Code CLI or another MCP-compatible AI agent.
Network access from the AI client host to the MCP server URL over HTTPS.

The MCP server uses HTTP POST with JSON-RPC 2.0 payloads. If your environment restricts outbound access, allow HTTPS traffic from the AI client host to the MCP server URL.

Setup

Setting up the MCP server involves obtaining an API key from the Stellar Cyber Platform and then configuring your AI client to connect using that key.

Get your API key.
1. Log in to your Stellar Cyber instance.
2. Select Profile | API Keys.
3. Select Create API Key.
4. Copy the API key and save it securely.
  
  You will need it when configuring your AI client.
Keep your API key secure. Treat it like a password. Never commit it to version control or share it publicly.
Configure your AI client.

You can configure the MCP server either with a command-line instruction or by editing the MCP configuration file of your AI client directly.

Option A: Using the Claude CLI (recommended). The quickest way to configure the MCP server is with the Claude CLI mcp add command:
Copy
```
claude mcp add --transport http stellar_api https://your-stellar-host/mcp/ \
--header "Authorization: Bearer YOUR_API_KEY_HERE"
```
Replace your-stellar-host with your actual Stellar Cyber hostname, and YOUR_API_KEY_HERE with the API key you saved in Step 1. A completed command looks similar to the following:
Copy
```
claude mcp add --transport http stellar_api https://soc.example.com/mcp/ \
--header "Authorization: Bearer sk-stellar-9f8e7d6c5b4a3210fedcba9876543210"
```
Option B: Manual configuration. If you prefer to configure the client manually, add the following entry to your MCP configuration file:
Copy
```
{
  "mcpServers": {
    "stellar_api": {
      "type": "http",
      "url": "https://your-stellar-host/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY_HERE"
      }
    }
  }
}
```
As with Option A, replace your-stellar-host with your Stellar Cyber hostname and YOUR_API_KEY_HERE with your API key.

Verify the Connection

After configuring the MCP server, confirm that your AI client can reach it before you begin working.

Check Connection Status

Open the MCP management interface of your AI client. In the Manage MCP servers view, check that the stellar_api server appears with a connected status. The name stellar_api is the connection name assigned to the MCP server when you configured it in Step 2. It is not the same as the hostname of your Stellar Cyber instance.

If the stellar_api server does not appear with a connected status, see theTroubleshooting section.

Test with a Simple Query

Restart your AI client and try a simple request, for example:

"Can you list recent most severe cases?"

If the MCP server is configured correctly, the AI client connects to your Stellar Cyber instance and returns the requested information.

How Authentication Works

The Stellar Cyber MCP Server uses a two-step authentication model that relies on two distinct kinds of token:

API key (refresh token). The long-lived credential you copy from the Stellar Cyber UI and place in your client configuration.
Access token. A short-lived token, valid for 10 minutes, used to authorize individual API requests.

Your AI client connects to the MCP server with the API key and receives a short-lived access token in return. The client then uses that access token for subsequent requests until it expires. When the token expires, the AI client automatically obtains a new access token and continues. This re-authentication does not require any action from you.

You only need to configure the API key. The AI client manages the access token lifecycle automatically—obtaining a token at the start of a session, reusing it, and refreshing it when it expires. Token expiry does not limit the overall length of your working session.

Permissions and Privilege Model

The MCP client uses your API key to interact with the Stellar Cyber Platform. Privileges are limited to the scope of this API key: the AI client can access only the resources and perform only the actions for which your API key is authorized.

If your API key has read-only access, the AI client cannot modify cases, regardless of how it is prompted.
Tenant access is also scoped by the API key. The AI client sees only the tenants that your user account is permitted to access.
Revoking the API key immediately disables MCP access for any client that uses it.

Use the MCP Server

Use the Stellar Cyber MCP Server when you want your AI client to retrieve investigation data from the Stellar Cyber Platform and assist with case review and case handling. In the current release, the MCP server supports several practical workflows. You can use it to list and search cases, open a case and review its details, retrieve related alerts and observables, examine investigation context such as MITRE ATT&CK mappings, and update selected case fields.

These capabilities are useful when you want an AI client to help you gather and organize investigation context before you take action in the Stellar Cyber Platform. For example, you can review the current state of a case, examine the alerts related to that case, retrieve observables for additional investigation, and then update case ownership, status, severity, or tags when needed. In multi-tenant environments, you can also use the MCP server to work across the tenants that are accessible to your credentials.

For most case-review tasks, the getCaseDetail operation is the preferred starting point. It consolidates case details, summary, alerts, comments, observables, activity, scores, and available assignees into a single call. Note that getCaseDetail returns inline details for up to 5 alerts; if a case includes more related alerts, use getCaseAlerts to retrieve the broader set. Also note that AI summary data is available only when the corresponding feature is enabled in the Stellar Cyber System Settings.

How It Works

Describe what you want to do in natural language, and your AI client will take the following actions:

Interpret your intent.
Select the appropriate MCP tool or tools.
Call the Stellar Cyber API on your behalf.
Present the results in a human-readable format.

The AI client automatically handles token management and authentication, parameter validation and formatting, error handling and retries, and multi-step workflows such as finding a case ID and then retrieving its details.

Example Workflow

This example shows a typical way to use the MCP server through an AI client:

Connect your AI client to the Stellar Cyber MCP server.
Confirm the connection shows a connected status.
Ask the AI client to list active or high-priority cases.
Select a case and request its complete details.
Review the related alerts, observables, MITRE ATT&CK mappings, comments, activity, threat scores, and summary information that the MCP server returns.
Ask the AI client to update the case status, severity, assignee, or tags as needed.

Example Use Cases

You can use the MCP server to support workflows such as these:

Triage open cases. Ask the AI client to list open or high-severity cases, identify the cases that need immediate attention, and summarize the basic context so that you can decide which case to review first.
Review investigation context before escalation. Retrieve the complete details for a case, including related alerts, observables, activity, comments, threat scores, and MITRE ATT&CK mappings, so that you can review the evidence before escalating the case.
Summarize case activity. Use the AI client to retrieve case details and produce a concise summary of what has happened in the case so far, including notable alerts, investigation findings, and recent changes.
Retrieve related alerts for analyst review. Start from a case, retrieve the alerts associated with it, and examine those alerts more closely to understand the sequence of detections.
Update case ownership or status during case handling. After reviewing a case, use the AI client to update the assignee, status, severity, or tags so that the case record reflects the current investigation state.

Sample Queries

The following are practical examples of requests you can make to your AI client.

Case discovery and triage

"Can you list recent most severe cases in 24 hours?"

"Show me all open critical cases assigned to me"

"Find cases related to ransomware from the last week"

"List unassigned high-severity cases"

"What cases were created today?"

Case investigation

"Please check detail of case 1300"

"Show me all alerts for case 1300"

"What are the observables in case 5432?"

"Get the activity timeline for case 789"

"What's the threat score for case 1300?"

Case assignment and management

"Who can I assign case 1300 to?"

"Please get one assignee to be assigned to handle case 1300"

Case updates

"Update case 1300 to in-progress status"

"Assign case 1300 to user john.doe@company.com"

"Change the severity of case 1300 to critical"

"Add tags 'phishing' and 'email' to case 1300"

"Mark case 1300 as resolved with resolution: false positive"

Multi-tenant operations

"List all tenants I have access to"

"Show me cases for the SOC tenant"

Supported API Calls

The Stellar Cyber MCP Server currently exposes the following operations.

Authentication

Operation	Description
`get_access_token`	Obtains a short-lived access token for API authentication. The token remains valid for 10 minutes. The AI client typically calls this once at the start of a session, reuses the token for subsequent requests, and obtains a new token automatically when the current token expires.

Case Operations

Operation	Description
`getCaseDetail`	Retrieves comprehensive case information in a single call, consolidating what would otherwise require multiple individual operations. Supports lookups by `ticket_id` (for example, `1300`) or the record `_id` parameter. An optional `include` parameter selects specific data sections; if you omit it, the response returns all sections. This is the recommended operation for retrieving case information.
`listCases`	Lists and searches security cases with filtering, sorting, and cursor-based pagination. Supports full-text searches across case content. Returns the `ticket_id` for each case, along with metadata such as case name, status, severity, score, assignee, and timestamps.
`getCaseAlerts`	Retrieves alerts related to a case, with pagination support. Use this operation when you need more alerts than the inline set of up to 5 returned by `getCaseDetail`.
`updateCase`	Updates selected case fields, such as status, severity, assignee, and tags, and can add resolution details when closing a case. Requires the `_id` parameter (not the ticket_id ). Field values are validated before changes are applied.

The getCaseDetail response is organized into the following sections. Use the include parameter to select specific sections.

Section	Content
`details`	Basic case information, such as status, severity, and assignee
`summary`	Case summary
`alerts`	Related alerts, up to 5
`comments`	List of comments
`observables`	Observables such as IP addresses, users, and hosts
`activity`	Audit logs and activities
`scores`	Risk scores
`assignees`	Assignee information
`aiSummary`	AI-generated summary, including timeline, hypothesis with MITRE ATT&CK mapping, key entities and relations, recommendations, a concise summary, a verdict (True Positive or False Positive classification), and the triage state. This section is available only when the corresponding feature is enabled in the Stellar Cyber System Settings.

The listCases operation supports the following filter and sort parameters.

Parameter	Description
`cust_id`	Filters by tenant ID. Use `listTenant` to discover tenant IDs.
`status`	Filters by case status, such as New, In Progress, or Resolved
`severity`	Filters by everity level: Critical, High, Medium, or Low
`assignee`	Filters by assignee username
`name`	Filters by case name
`tags`	Filters by a comma-separated list of tags
`min_score`	Filters by a minimum risk score threshold
`search`	Full-text search term applied across case fields
`from_created_at / to_created_at`	Created-at range, in UTC epoch milliseconds. Specify both bounds together.
`from_modified_at / to_modified_at`	Modified-at range, in UTC epoch milliseconds. Specify both bounds together.
`sort`	Field to sort by, such as `created_at`, `modified_at`, `score` , or `severity`
`order`	Sort direction: `asc` or `desc`.
`limit`	Number of results per page
`cursor`	Pagination cursor from a previous response

Default 24-hour time window. If you specify neither a created-at range nor a modified-at range, the MCP server automatically applies a created-at range covering the previous 24 hours. This prevents accidental full-table scans on large deployments. Explicit values always override this default. When you specify a range, provide both bounds together; providing only one bound can still cause timeouts on large deployments.

Alert Operations

Operation	Description
`getAlertDetail`	Retrieves full details for a single alert, returning the complete Elasticsearch document, which includes information such as IP addresses, geolocation, MITRE ATT&CK mapping, XDR event metadata, and severity. Use this operation for a deeper investigation of an alert referenced from a case. The required input is the `alert_id` (a `stellar_uuid`); the database index is detected automatically from the ID. When the corresponding feature is enabled in the Stellar Cyber System Settings, the response also includes an AI-generated alert summary. If that feature is not enabled, an entry appears in the `errors` array and the database record is still returned.

Operation

Description

getAlertDetail Retrieves full details for a single alert, returning the complete Elasticsearch document, which includes information such as IP addresses, geolocation, MITRE ATT&CK mapping, XDR event metadata, and severity. Use this operation for a deeper investigation of an alert referenced from a case. The required input is the alert_id (a stellar_uuid); the database index is detected automatically from the ID. When the corresponding feature is enabled in the Stellar Cyber System Settings, the response also includes an AI-generated alert summary. If that feature is not enabled, an entry appears in the errors array and the database record is still returned.

Tenant Operations

Operation	Description
`listTenant`	Lists the tenants accessible to your credentials. Useful in multi-tenant environments. Supports field projection for customized responses.
`getTenant`	Retrieves details for a specific tenant. Use this operation to validate tenant access or to obtain tenant-specific context before performing tenant-scoped operations.

Troubleshooting

The AI Client Cannot Connect to the MCP Server

If the connection fails, use the Reconnect option to re-establish the connection with your existing API key configuration:

1. Open the MCP management interface of your AI client.

2. Select the stellar_api server.

3. Select Reconnect from the menu.

4. Wait for the connection to re-establish.

If reconnecting does not resolve the issue, also verify that the MCP server URL is correct (typically https://your-stellar-host/mcp/), that the AI client host can reach the URL over HTTPS, and that your firewall policy allows outbound HTTPS access to the MCP server destination.

Authentication Fails

Verify that you copied the complete API key from Stellar Cyber and that the Authorization header is formatted as Bearer YOUR_API_KEY. Also confirm that your user account has the permissions required for the operations you are attempting. If the API key is correct and authentication still fails, verify that the client is configured to connect to the correct MCP server URL.

Requests Start Failing After a Period of Successful Use

Access tokens expire after 10 minutes. When a token expires, the AI client automatically obtains a new one, so a brief interruption is normal and does not require any action from you. If requests continue to fail, the cause is more likely the API key itself. Verify that your API key (refresh token) is still valid and has not been revoked, and generate a new API key from the Stellar Cyber UI if necessary.

No Stellar Cyber Tools Are Available

Tools are the individual operations that the MCP server exposes to your AI client, such as listCases and getCaseDetail . If the AI client cannot find any Stellar Cyber tools, first use the Reconnect option in the MCP server details menu, as this resolves most connection issues. If tools are still unavailable, verify that the MCP server feature is enabled on your Stellar Cyber instance, confirm that stellar_api shows a connected status, restart your AI client, and review the logs of the AI client for error messages.

Case Details Do Not Include All Related Alerts

getCaseDetail returns inline alert details for up to 5 alerts. If a case includes more related alerts, use getCaseAlerts to retrieve the broader alert set.

AI Summary Data Is Missing

AI summary data is available only when the corresponding feature is enabled in the Stellar Cyber System Settings. If that feature is not enabled, the case detail response does not include the aiSummary section.

Tenant Data Is Missing or Incomplete

The MCP server is tenant-aware. The data returned to the AI client depends on the tenants that are accessible to your credentials.

How Errors Are Reported

Your AI client handles authentication, authorization, and other operational errors. When the MCP server returns an error response, the AI client surfaces the error message to you in the conversation so that you can take action. You do not need to inspect server logs to diagnose typical issues, because the response from your AI client already contains the relevant error message from the MCP server.

Auditing MCP Access

All data access performed through the MCP server is recorded as Public API access in the Stellar Cyber Activity Log, which you can review from the Stellar Cyber UI.

To view MCP activity:

Log in to your Stellar Cyber instance.
Select System | User | Activity Log.
Filter by your username, or by the activity type Public API access.

Each entry shows the timestamp, the user, the API endpoint accessed, and the source. Every tool call made by the AI client—such as a case lookup, a case update, an alert detail retrieval, or a tenant query—is recorded as a Public API access entry, and every entry is attributable to the owner of the API key. Administrators can audit MCP usage from the same UI used for any other Public API usage; there is no separate log category for MCP. This gives you full visibility into what the AI client has accessed or modified on your behalf.

Security Best Practices

Never share your API key. Treat it like a password.
Use HTTPS. Always connect over secure https:// connections.
Rotate keys regularly. Generate new API keys periodically for better security.
Limit permissions. Create API keys with only the permissions needed for your use case.
Monitor usage. Regularly review API key usage in your Stellar Cyber instance. See Auditing MCP Access for how to review this activity.

Disclaimer. AI clients connected through the MCP server can read the data you integrate. It is your responsibility to review the AI client settings and to properly manage the handling of sensitive or confidential information.