MCP (Model Context Protocol) - MindFort Documentation

To set up MindFort with your agent, use the copyable prompt in Quickstart for agents.

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 coverage scenarios, run states, and linked findings
Discovering candidate targets when Discovery is enabled
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

Your agent can work with data available to your MindFort account. Use 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 incomplete coverage checks and summarize their latest run results.`

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.

MCP access requires active organization membership and the applicable permissions and features. If your membership or permissions change, reconnect and confirm your access with get_current_context.

The catalog depends on the member’s role and organization features. Members whose only role is auditor have read-only access to permitted operations. 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

To help your agent use the correct context and resource IDs, 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, coverage check, 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
Coverage	Read current scenarios, run summaries, and linked findings
Discovery	Configure discovery, run it, and review candidate targets when enabled
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`
Coverage	`list_coverage_checks`, `get_coverage_overview`
Discovery	`get_discovery_status`, `update_discovery_schedule`, `update_discovery_context`, `start_discovery_run`, `cancel_discovery_run`, `list_discovery_suggestions`, `accept_discovery_suggestion`, `dismiss_discovery_suggestion`
Assessments	`list_assessments`, `get_assessment`, `run_assessment`, `cancel_assessment`
Assessment schedules	`list_assessment_schedules`, `get_assessment_schedule`, `create_assessment_schedule`, `update_assessment_schedule`, `delete_assessment_schedule`, `trigger_assessment_schedule`, `pause_assessment_schedule`, `resume_assessment_schedule`
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:

discovery: discovery status, context, schedules, runs, and suggestions
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

If your available features or permissions change, reconnect or start a new chat to refresh the tools available to your agent.

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 list and detail reads return metadata only; they do not return passwords, API-key values, or TOTP seeds. Dedicated authentication helpers can return a temporary code or login URL, and email provisioning returns a pending inbox ID for credential creation. 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. Use stage_progress in the get_assessment response to track assessment stages:

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 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 failure_reason explaining the problem. cancel_assessment accepts only the assessment ID. Record any cancellation context in your own workflow.

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 result indicating the issue is fixed under the tested conditions sets the finding to RESOLVED; a result indicating it remains reproducible sets it to 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. If the connection returns HTTP 429 Too Many Requests, wait for the Retry-After interval before retrying and reduce polling frequency. 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.

Coverage and discovery

Use list_coverage_checks for individual scenarios and get_coverage_overview for aggregate counts. Keep covered, failing, incomplete, in_progress, and not_run separate when summarizing results. Coverage is read-only; there are no tools to create, edit, or rerun a check. Discovery proposes candidate targets. Accepting a suggestion creates a target; inspect its verification state before starting testing. Discovery tools appear only when the feature is enabled.

​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

​Coverage and discovery

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

Coverage and discovery