MCP (Model Context Protocol) - MindFort Documentation

What You Can Do

Connect Cursor, Claude Code, Codex, or another MCP client to MindFort and work with your organization’s security program from your agent. The MindFort MCP server exposes an explicit, organization-scoped tool catalog for:

Browsing, creating, updating, and deleting authorized targets
Managing write-only test credentials for web applications and APIs
Reviewing secure-anchor coverage and managing user-defined anchors
Starting, monitoring, and canceling assessments
Browsing, triaging, commenting on, and retesting findings
Reading security metrics, distributions, aging, remediation, and health scores
Generating, polling, and downloading reports

MindFort remains the source of truth. Your agent receives positive-allowlisted public fields and uses resource IDs returned by MindFort instead of guessing identifiers.

MCP Use Cases

Use Case	Example Prompt
Check current posture	`Show my current MindFort metrics, coverage gaps, and critical active findings.`
Monitor an assessment	`List my active assessments and show the stage progress for the newest one.`
Investigate a finding locally	`Pull this MindFort finding, inspect the relevant code, and explain the vulnerable path.`
Generate a local patch	`Use the evidence and remediation advice to patch this finding in my working tree.`
Retest after deployment	`Add a deployment note, start a retest, and poll the finding until it finishes.`
Prepare a report	`Generate a condensed report for this target and give me the download URL when ready.`
Configure API testing	`Show the target metadata and credential types required for authenticated API testing.`
Review coverage gaps	`List blocked secure anchors and summarize their required actions.`

MCP vs. Platform Patching

Use Patching when you want MindFort to generate a pull request directly from the platform. Use MCP when you want your local AI agent to combine MindFort evidence with your repository checkout, build system, and engineering conventions.

Install

Cursor

Or add the server to .cursor/mcp.json:

{
  "mcpServers": {
    "MindFort": {
      "url": "https://api.mindfort.app/mcp",
      "transport": "http"
    }
  }
}

Claude Code

claude mcp add --transport http MindFort https://api.mindfort.app/mcp

Then run /mcp inside Claude Code to sign in. Or add the server to .mcp.json:

{
  "mcpServers": {
    "MindFort": {
      "type": "http",
      "url": "https://api.mindfort.app/mcp"
    }
  }
}

Codex

codex mcp add MindFort --url https://api.mindfort.app/mcp

Or add the server to ~/.codex/config.toml:

[mcp_servers.MindFort]
url = "https://api.mindfort.app/mcp"

Other MCP Clients

Use the Streamable HTTP endpoint:

https://api.mindfort.app/mcp

MindFort uses stateless Streamable HTTP: clients send MCP requests with POST /mcp. The legacy HTTP+SSE transport and the old GET /mcp stream and DELETE /mcp session methods are not supported. MindFort MCP uses browser-based OAuth with your existing MindFort account. You do not need an API key.

Add the MindFort MCP server.
Complete the browser sign-in when your client prompts you.
Select the intended MindFort organization.
Ask the agent to call get_current_context and confirm the organization, role, and enabled capabilities.

Each MCP request revalidates your active WorkOS organization membership and effective feature flags. Removing or deactivating a membership takes effect without waiting for the OAuth token to expire.

Every active organization member receives the baseline registered MCP catalog. Feature-gated tools and credential variants appear only when their organization has the corresponding feature enabled. MindFort does not expose billing administration, API-key administration, organization membership, or role administration over MCP.

Start with Context

For reliable agent workflows, use this sequence:

Call get_current_context to confirm the selected organization and available capabilities.
Call list_targets, then get_target before target-specific work.
Reuse target, credential, assessment, finding, anchor, and report IDs returned by MindFort.
Review tool warnings before starting active testing or performing destructive actions.
Poll asynchronous operations with their corresponding read tool.

The server also exposes the fixed resource mindfort://guides/start-here. MCP clients that support resources can discover and read it for the compact operating sequence. For detailed semantics, use this documentation and the agent-readable documentation index.

Capabilities and Feature Gating

The tool catalog is explicit and may differ by organization.

Area	Typical workflow
Targets	`list_targets` -> `get_target` -> create, update, or confirmed deletion
Credentials	List safe metadata; create, rotate, or delete write-only test credentials
Secure anchors	Read coverage, inspect individual decisions, and manage user-created anchors
Assessments	`run_assessment` -> poll `get_assessment` -> inspect findings
Findings	List/get, update lifecycle, comment, override severity, retest, and inspect patch summaries
Analytics	Read counts, distributions, health, history, timeseries, remediation, SLA, and aging
Reports	`create_report` -> poll `get_report` -> `download_report`

Complete tool catalog

The baseline and feature-gated catalog contains the following tools. Call get_current_context first because feature-gated tools may be absent for the selected organization.

Area	Tools
Context	`get_current_context`
Targets	`list_targets`, `get_target`, `create_target`, `update_target`, `delete_target`
Credentials	`list_target_credentials`, `create_target_credential`, `update_target_credential`, `delete_target_credential`, `generate_target_email_credential`, `check_email_mfa`, `get_authenticator_2fa_code`, `get_sms_credentials_access`, `list_sms_credential_countries`, `check_sms_code`
Secure anchors	`get_secure_anchor_coverage`, `list_secure_anchors`, `list_target_secure_anchors`, `create_secure_anchor`, `update_secure_anchor`, `archive_secure_anchor`
Assessments	`list_assessments`, `get_assessment`, `run_assessment`, `cancel_assessment`
Findings	`list_findings`, `get_finding`, `update_finding_status`, `update_finding_statuses`, `update_finding_severity`, `retest_finding`, `add_finding_comment`, `list_finding_comments`, `edit_finding_comment`, `delete_finding_comment`, `list_finding_patches`, `get_patch_count`
Analytics	`get_finding_counts`, `get_severity_distribution`, `get_target_health_score`, `get_category_distribution`, `get_severity_score_history`, `get_current_security_metrics`, `get_security_metrics_timeseries`, `get_remediation_metrics`, `get_sla_metrics`, `get_finding_aging`
Reports	`create_report`, `list_reports`, `get_report`, `download_report`

Feature-gated capabilities include:

network-targets: network target creation and assessment inputs
sms-credentials: SMS credential variants, provisioning metadata, and code checks
finding-severity-overrides: setting severity overrides; clearing an existing override remains available

The server refreshes membership and feature state on each request. Some clients cache tool discovery for a conversation or process, so reconnect or start a new chat after a catalog-changing deployment or entitlement change.

Targets and Credentials

Web application and API targets require an HTTP(S) web_domain. Network targets require an ip_address and are available only when enabled for the organization. Targets created through REST or MCP start unverified; complete ownership or network verification in the MindFort dashboard before active testing. Credential reads return metadata only. Passwords, API-key values, TOTP seeds, one-time codes, and pending inbox IDs are never returned. For API targets, api_key credentials require nonblank target-level api_auth_instructions that explain:

The validation route and HTTP method
The required request shape
Where the key is placed, such as a bearer token, header, query parameter, or JSON field
The expected successful response

Secrets are write-only. Rotate a secret through the update tool instead of expecting to read it back.

Assessments and Stage Progress

Starting an assessment begins active security testing and may consume plan capacity. Use only a target the user intends to test. get_assessment returns the canonical stage_progress roster. It merges the current expected plan with every stage recorded on that assessment:

NOT_STARTED means no state has been recorded.
RUNNING or ACTIVE means work is in progress.
Other values are terminal stage outcomes.
Active testing stages may include customer-safe executor status, attempt, and timing fields.

Top-level created_at, updated_at, started_at, and completed_at describe the full run. Failed runs may include a bounded failure_reason. Cancellation accepts an optional cancel_reason for the audit trail.

Findings and Retests

The list_findings tool accepts the same filters as GET /v1/findings.

Argument	Default	Description
`target_id`	—	Limit to one target
`assessment_id`	—	Limit to one assessment run
`status`	`ACTIVE`	`ACTIVE`, `RESOLVED`, or `ARCHIVED`
`exclude_secured`	`false`	Omit informational secured probes when `true`
`severity`	—	`critical`, `high`, `medium`, `low`, or `secured`
`sort_by`	`severity`	`severity` or `created_at`
`limit`	Tool-specific	Bounded page size
`cursor`	—	Opaque continuation cursor from the previous result

Use total for the full matching count rather than the first page length. To match the dashboard Open tab, use status=ACTIVE and exclude_secured=true. Retests are asynchronous and may be started for ACTIVE, RESOLVED, or ARCHIVED findings. Poll get_finding:

QUEUED or RUNNING: execution is still active.
FAILED: retest_failure_reason explains why execution could not complete.
COMPLETED: validation finished and the result was applied. A fixed finding becomes RESOLVED; a still-vulnerable finding becomes ACTIVE.

See Findings API for REST examples and field details.

Pagination

MCP list tools use opaque cursors rather than REST offsets. When a result includes next_cursor, pass it back unchanged with the same filters. Cursors are bound to the operation and filter set, so changing filters requires starting a new pagination sequence. tools/list returns the complete authorized catalog and is not paginated.

Errors and Sensitive Actions

Tool failures include a stable error code, safe message, retry guidance when applicable, and a request ID for support correlation. Validation errors may also include field-level details. Common actionable codes include:

target_not_verified
api_auth_instructions_required
assessment_already_running
assessment_credits_insufficient
assessment_queue_loading
retest_already_running

Destructive tools have prominent warnings and MCP destructive annotations. Invoking the tool performs the action after normal validation; MindFort does not add a second approval handshake. Review target names, resource IDs, and warnings before deletion, cancellation, archival, or active testing.

Troubleshooting

Agent can't connect

Confirm the URL is exactly https://api.mindfort.app/mcp, your network allows HTTPS, and your client supports Streamable HTTP. Restart the client and try again.

Expected tools are missing

Call get_current_context to confirm the selected organization and its public feature flags. Then reconnect or start a new chat so the client refreshes tool discovery.

Finding disappears after resolving

This is expected when list_findings uses the default status=ACTIVE. Pass status=RESOLVED or status=ARCHIVED to browse those lifecycle states.

API or MCP count differs from the dashboard

The dashboard Open tab hides informational secured probes by default. Pass exclude_secured=true and status=ACTIVE to match it. Use assessment_id when comparing one assessment.

A cursor is rejected

Pass next_cursor back unchanged with the same tool and filters. Start over without a cursor after changing filters.

​What You Can Do

​MCP Use Cases

​MCP vs. Platform Patching

​Install

​Cursor

​Claude Code

​Codex

​Other MCP Clients

​Sign In and Authorization

​Start with Context

​Capabilities and Feature Gating

​Complete tool catalog

​Targets and Credentials

​Assessments and Stage Progress

​Findings and Retests

​Pagination

​Errors and Sensitive Actions

​Troubleshooting

What You Can Do

MCP Use Cases

MCP vs. Platform Patching

Install

Cursor

Claude Code

Codex

Other MCP Clients

Sign In and Authorization

Start with Context

Capabilities and Feature Gating

Complete tool catalog

Targets and Credentials

Assessments and Stage Progress

Findings and Retests

Pagination

Errors and Sensitive Actions

Troubleshooting