MCP Server Integration

By the end of this page, you'll have the Plexicus MCP server running in your IDE (Claude Code, Cursor, VS Code, or Windsurf), able to discover security findings, generate AI remediations, and run scans without leaving your editor.

What the MCP server gives you

The Plexicus MCP server exposes your entire security posture to AI agents inside your IDE. Query repositories, list critical findings, generate fixes, request scans, and triage results—all from the IDE's chat interface—while the AI agent automates follow-up tasks.

Key capabilities:

Repository discovery: Auto-detect which Plexicus repository matches your local workspace.
Findings query: List findings by severity, status, or CWE; read full details and code context.
AI remediation: Generate fix suggestions with diffs and guidance; apply them to your workspace.
Scan orchestration: Request app scans and poll progress in real-time.
Security posture: Snapshot account-wide summary—total findings by severity, worst repositories.

The server works with any MCP-compatible IDE client and runs on Python 3.10+.

Installation matrix

Choose your installation method based on your setup:

Method	Command	Requirements	Best for
uvx (recommended)	`uvx plexicus-mcp`	`uv` CLI installed	Zero-install, isolated environments
pipx	`pipx run plexicus-mcp`	`pipx` installed	Isolated, no PATH pollution
pip	`pip install plexicus-mcp` → `plexicus-mcp`	Python 3.10+ + pip	Manual control, CI/CD pipelines

Installation details

Using uvx (recommended):

# No installation needed; uvx manages the environment
`uv` will download and run `plexicus-mcp` in an isolated environment.

Using pipx:

pipx run plexicus-mcp

Using pip:

pip install plexicus-mcp
plexicus-mcp

All methods start the MCP server on stdio, ready to be invoked by your IDE.

IDE Setup

Claude Code

Add Plexicus to Claude Code with a single command:

claude mcp add plexicus \
  -e PLEXICUS_API_TOKEN=<your-token> \
  -e PLEXICUS_API_URL=https://api.app.plexicus.ai \
  -- uvx plexicus-mcp

Placeholders:

<your-token>: Your API token (see Token Generation below)
https://api.app.plexicus.ai: SaaS Plexicus API (replace with your self-hosted URL if using self-hosted)

After running this command, restart Claude Code and the Plexicus server will be available to agents.

Cursor, VS Code, Windsurf

Add Plexicus to your IDE's MCP configuration file (mcp.json or settings):

{
  "mcpServers": {
    "plexicus": {
      "command": "uvx",
      "args": ["plexicus-mcp"],
      "env": {
        "PLEXICUS_API_TOKEN": "<your-token>",
        "PLEXICUS_API_URL": "https://api.app.plexicus.ai"
      }
    }
  }
}

Location of mcp.json:

VS Code: ~/.config/Code/User/globalStorage/mcp.json (Linux/Mac) or %APPDATA%\Code\User\globalStorage\mcp.json (Windows)
Cursor: ~/.cursor/mcp.json (Mac/Linux) or %APPDATA%\.cursor\mcp.json (Windows)
Windsurf: Consult Windsurf documentation for MCP configuration path

Replace <your-token> and <url> as described above, then reload your IDE.

Token generation

Your API token identifies you to the Plexicus API. Generate one in the platform:

Log in to Plexicus
Go to Settings → API Tokens
Click Generate Token
Name your token (e.g., "Claude Code", "IDE", "local-dev")
Choose expiry: 30 days, 90 days, or Never expires
Click Generate
Copy the token immediately (it will not be shown again)
Paste it into the PLEXICUS_API_TOKEN environment variable in your IDE setup

Rolling out with the MCP release

The Settings → API Tokens page ships together with the MCP server release. If your workspace does not show it yet, it is being rolled out — contact support to enable it, or use your existing automation token in the meantime.

Token security: Treat your API token like a password. Never commit it to version control. Use environment variables or your IDE's secure credential storage.

Expiry and revocation: To revoke a token, return to Settings → API Tokens and click Revoke next to the token. Revoked tokens stop working immediately.

Environment variables

The MCP server reads two environment variables:

Variable	Required	Default	Description
`PLEXICUS_API_TOKEN`	Yes	—	Bearer token from Settings → API Tokens
`PLEXICUS_API_URL`	No	`https://api.app.plexicus.ai`	Base URL of Plexicus API; override for self-hosted deployments

Example for self-hosted:

claude mcp add plexicus \
  -e PLEXICUS_API_TOKEN=<token> \
  -e PLEXICUS_API_URL=https://plexicus.company.internal \
  -- uvx plexicus-mcp

Available tools

The MCP server exposes 10 tools. Use them in your IDE agent conversations by mentioning them by name (e.g., "use list_findings to show critical issues") or let the AI agent call them automatically.

`get_current_repository(path=".")`

Auto-detect which Plexicus repository matches your local workspace by reading git remote URLs.

Parameters:

path (string, optional): Path to git repository (default: workspace root)

Returns: Repository ID, name, remote URLs, and finding counts.

Example: Use this at the start of a security review to map your workspace to Plexicus.

`list_repositories(search=None, limit=25, cursor=None)`

List all repositories in your Plexicus account with finding severity counts.

Parameters:

search (string, optional): Filter by repository name (client-side)
limit (integer, default 25): Page size
cursor (string, optional): Pagination cursor from previous response

Returns: Markdown table of repositories + severity counts + pagination cursor.

Example: "Show me the 5 riskiest repositories" → the AI queries this tool and prioritizes by critical count.

`get_repository(repository_id)`

Fetch full details of a single repository (URLs, scan state, severity breakdown).

Parameters:

repository_id (string, required): Repository ID from list_repositories or get_current_repository

Returns: Repository name, URLs, scan status, and finding counts.

`list_findings(repository_id=None, severity=None, status=None, search=None, cwe=None, finding_type="app", sort=None, limit=25, cursor=None)`

Query security findings with advanced filtering.

Parameters:

repository_id (string, optional): Filter by one repository
severity (string, optional): Comma-separated list (e.g., "critical,high")
status (string, optional): Comma-separated list (e.g., "open,fixed")
search (string, optional): Text search on finding title
cwe (string, optional): Filter by CWE identifier
finding_type (string, default "app"): Type filter (e.g., "app", "cloud")
sort (string, optional): Sort key (e.g., "-created_at")
limit, cursor: Pagination

Returns: Markdown table of findings + raw data for automation.

Example: "List critical findings in this repo" → tool filters by severity and repository.

`get_finding(finding_id)`

Fetch the full detail of a single finding: title, severity, file path, line number, CWE, description, status, and scanner origin.

Parameters:

finding_id (string, required): Finding ID from list_findings

Returns: Human-readable summary + raw finding data.

Example: "Tell me more about that SQL injection" → tool retrieves full context.

`request_scan(repository_id, scan_type="app")`

Trigger a security scan of a repository (SAST/SCA/secrets/containers).

Parameters:

repository_id (string, required): Repository to scan
scan_type (string, default "app"): Type (e.g., "app" for application scanning)

Returns: Scan status "queued" + acknowledgment.

Note: Scans run asynchronously (typically 5–15 minutes). Use get_scan_status to poll progress.

Example: "Run a full scan" → tool queues the scan; agent then polls status.

`get_scan_status(repository_id)`

Check the current scan state and latest severity counts of a repository.

Parameters:

repository_id (string, required): Repository to check

Returns: Scan status ("in-progress", "completed", etc.) + current finding counts.

Example: Poll this every 30 seconds after calling request_scan to monitor progress.

`generate_remediation(finding_id)`

Request the AI remediation engine to generate a fix (diff + guidance) for a finding.

Parameters:

finding_id (string, required): Finding to remediate

Returns: Status "queued" + acknowledgment.

Note: Generation is asynchronous (typically 30–120 seconds). Use get_remediation to poll until ready.

Example: "Fix this SQL injection" → tool queues generation; agent then polls get_remediation.

`get_remediation(finding_id)`

Fetch the generated remediation (404 until generation completes).

Parameters:

finding_id (string, required): Finding ID from earlier

Returns: Diff (unified format), guidance text, and status "ready".

Example: Once ready, the AI presents the diff and guidance; you can review and apply it.

`get_security_posture()`

Get account-wide security posture summary: total findings by severity + worst 5 repositories.

Parameters: None

Returns: Total finding counts by severity + list of riskiest repositories.

Example: "Show me our security posture" → tool provides a bird's-eye view.

Guided workflows

The MCP server includes three guided prompts that orchestrate multiple tools to complete common tasks.

Fix a critical finding without leaving the IDE

Ask your IDE agent: "Fix the SQL injection in my current repo"
Agent calls get_current_repository() → maps workspace to Plexicus repo
Agent calls list_findings(severity="critical") → fetches critical findings
Agent calls get_finding(finding_id) → reads the vulnerability details and file location
Agent opens the file in your workspace and understands the code
Agent calls generate_remediation(finding_id) and polls get_remediation() until ready
Agent presents the diff and guidance; you review and apply it to the workspace
Agent runs tests and linters; reports what changed and why it fixes the vulnerability

Triage findings by real risk

Ask your IDE agent: "Triage the findings"
Agent calls get_current_repository() and list_findings(severity="critical,high")
For each finding, agent calls get_finding(), reads code context, and assesses exploitability
Agent produces a prioritized list: Fix now (reachable, user input flows) / Fix soon (edge cases) / Likely false positive
You then ask the agent to start with the top-priority finding using the fix workflow above

Run a full security review

Ask your IDE agent: "Run a security review"
Agent calls get_current_repository() → maps workspace
Agent calls request_scan() and polls get_scan_status() every 30 seconds
Scan completes (typically 5–15 minutes); agent calls list_findings(severity="critical,high")
Agent summarizes the posture and highlights newly introduced findings
Agent proposes next steps: which findings to remediate first

Troubleshooting

"Authentication failed" or "401 Unauthorized"

Cause: The PLEXICUS_API_TOKEN is invalid, expired, or revoked.

Fix:

Log in to Plexicus Settings
Verify the token exists and check its expiry date
If expired or revoked, generate a new token (see Token Generation)
Update PLEXICUS_API_TOKEN in your IDE config
Restart your IDE

"Connection refused" or "Cannot reach API"

Cause: The PLEXICUS_API_URL is incorrect or the server is unreachable.

Fix:

For SaaS: Verify PLEXICUS_API_URL=https://api.app.plexicus.ai (the default)
For self-hosted: Check that the URL is correct and the server is running
Test connectivity: curl -H "Authorization: Bearer $PLEXICUS_API_TOKEN" https://api.app.plexicus.ai/repositories (replace the URL if self-hosted)

"uvx: command not found"

Cause: The uv CLI is not installed.

Fix: Install uv from astral.sh/uv. Then retry the setup command.

Alternatively, use pipx run plexicus-mcp or pip install plexicus-mcp instead of uvx.

"MCP server is not responding"

Cause: The server crashed or is not running.

Fix:

Restart your IDE
Check that environment variables are set correctly

Try running the server manually to see error output:

export PLEXICUS_API_TOKEN=<your-token>
uvx plexicus-mcp

Self-hosted: "Certificate verification failed"

Cause: Self-signed SSL certificate (common in air-gapped environments).

Fix: Your MCP client should respect standard SSL verification settings. If you have a self-signed cert, either:

Add the cert to your system's trusted CA store, or
Work with your Plexicus admin to install a proper certificate

Package version

The plexicus-mcp package is published independently to PyPI and is compatible with all Plexicus SaaS and self-hosted versions. The current release supports Python 3.10, 3.11, 3.12, and 3.13.

For the latest version and release notes, see plexicus-mcp on PyPI.

What the MCP server gives you​

Installation matrix​

Installation details​

IDE Setup​

Claude Code​

Cursor, VS Code, Windsurf​

Token generation​

Environment variables​

Available tools​

get_current_repository(path=".")​

list_repositories(search=None, limit=25, cursor=None)​

get_repository(repository_id)​

list_findings(repository_id=None, severity=None, status=None, search=None, cwe=None, finding_type="app", sort=None, limit=25, cursor=None)​

get_finding(finding_id)​

request_scan(repository_id, scan_type="app")​

get_scan_status(repository_id)​

generate_remediation(finding_id)​

get_remediation(finding_id)​

get_security_posture()​

Guided workflows​

Fix a critical finding without leaving the IDE​

Triage findings by real risk​

Run a full security review​

Troubleshooting​

"Authentication failed" or "401 Unauthorized"​

"Connection refused" or "Cannot reach API"​

"uvx: command not found"​

"MCP server is not responding"​

Self-hosted: "Certificate verification failed"​

Package version​

What the MCP server gives you

Installation matrix

Installation details

IDE Setup

Claude Code

Cursor, VS Code, Windsurf

Token generation

Environment variables

Available tools

`get_current_repository(path=".")`

`list_repositories(search=None, limit=25, cursor=None)`

`get_repository(repository_id)`

`list_findings(repository_id=None, severity=None, status=None, search=None, cwe=None, finding_type="app", sort=None, limit=25, cursor=None)`

`get_finding(finding_id)`

`request_scan(repository_id, scan_type="app")`

`get_scan_status(repository_id)`

`generate_remediation(finding_id)`

`get_remediation(finding_id)`

`get_security_posture()`

Guided workflows

Fix a critical finding without leaving the IDE

Triage findings by real risk

Run a full security review

Troubleshooting

"Authentication failed" or "401 Unauthorized"

"Connection refused" or "Cannot reach API"

"uvx: command not found"

"MCP server is not responding"

Self-hosted: "Certificate verification failed"

Package version