Skip to navigation

MCP Server

Overview

Pensar provides a remote Model Context Protocol (MCP) server that lets AI tools interact directly with your Pensar workspace. Through MCP, you can list scans, launch pentests, review security issues, and retrieve auto-generated fixes using tools like Claude Code, Desktop, or Web, or even directly in Slack.

MCP is an open standard that allows AI assistants to connect to external tools and data sources. Pensar’s MCP server implements the Streamable HTTP transport so it works with any MCP-compatible client.

Prerequisites

Before connecting an MCP client to Pensar you need:

  • A Pensar Console account at console.pensar.dev
  • At least one workspace with a connected repository
  • An MCP-compatible client (e.g., Claude Desktop, Claude Code, Cursor, Windsurf)

Server URL

The Pensar MCP server is available at:

https://api.pensar.dev/mcp

Authentication

The Pensar MCP server uses OAuth 2.0 for authentication, following the MCP Authorization specification (2025-03-26). When you first connect, your MCP client will open a browser window where you sign in with your Pensar Console credentials. After signing in, the client receives a token and uses it automatically for all subsequent requests.

Most MCP clients handle the OAuth flow automatically. You do not need to create or manage API keys, just sign in.

Setup

  1. Open Claude Code by running claude in your terminal
  2. Add the Pensar MCP server:
claude mcp add Pensar --transport http https://api.pensar.dev/mcp
  1. Run the /mcp command, you’ll see Pensar with a needs authentication status
  2. Select it and choose Authenticate to sign in with Pensar in your browser

Toolsets

A connection exposes every tool by default. To give an agent only some of them, name the toolsets you want, comma-separated, in a toolsets query parameter on the server URL:

https://api.pensar.dev/mcp?toolsets=issues,fixes

If your client lets you set request headers, you can send the same list in an X-MCP-Toolsets header instead:

X-MCP-Toolsets: issues,fixes

An unknown toolset name is rejected with a 400 error that lists the valid names.

ToolsetTools
pentestslist_scans, get_scan, dispatch_pentest, list_pentest_targets
issueslist_issues, get_issue, get_issue_evidence, list_issue_retests, update_issue, retest_issue, link_pull_request, list_issue_pull_requests, list_comments, create_comment
fixeslist_fixes, get_fix
incidentslist_incidents, list_incident_events, get_incident, list_incident_logs, get_incident_log_attachment
logslist_agent_logs, search_agent_logs, list_target_logs, search_target_logs
knowledgelist_knowledge, get_knowledge, create_knowledge, update_knowledge, archive_knowledge
inventorylist_applications, get_application, search_applications, create_application, update_application, delete_application, list_endpoints, get_endpoint, get_endpoints, search_endpoints, create_endpoint, update_endpoint, delete_endpoint, list_domains, create_domain

Available Tools

The Pensar MCP server exposes the following tools to your AI coding agent:

Scans

List all scans in your workspace.

Parameters: None

Returns: A list of scans with their IDs, labels, statuses, scan types, branches, and timestamps.

Example prompt: “Show me all my Pensar scans.”

Get detailed information about a specific scan.

Parameters:

ParameterTypeRequiredDescription
scanIdstringYesScan ID to retrieve details for

Returns: Detailed scan information including workspace name, status, error messages, issue count, and whether a report is ready.

Example prompt: “What’s the status of scan xyz-789?”

List the targets of a pentest. Each target is an attack-surface endpoint the pentest exercised. Use a target ID to read its logs with list_target_logs or search_target_logs, even when the target produced no issue.

Parameters:

ParameterTypeRequiredDescription
pentestIdstringYesPentest ID, from list_scans

Returns: Each target’s ID, URL, application, status, attempt count, start and completion times, and any error. API keys require pentests:read.

Queue a hosted pentest in the authenticated workspace. The scan runs asynchronously; an identical active launch may be reused.

Parameters:

ParameterTypeRequiredDescription
endpointIdsstring[]NoExact list of 1–1000 discovered endpoint UUIDs in this workspace. Cannot be combined with branch; only full depth is supported.
scanLevelstringNo"priority" or "full". Defaults to "full" with endpointIds, otherwise "priority". "priority" is rejected with endpointIds.
branchstringNoMust match the connected repository’s configured target branch, which is used when omitted. Cannot be combined with endpointIds.
knowledgeEntryIdsstring[]NoUp to 20 active knowledge base entry UUIDs to give the run as context (see Knowledge Base).
customTestobjectNoRun a custom test driven by your own instructions. brief (string, up to 20,000 characters) is applied to every listed application; applications is a list of { applicationId, endpointIds? }, where endpointIds limits that application to those of its endpoints and omitting it tests the whole application. Runs at full depth. Cannot be combined with top-level endpointIds, branch, or scanLevel: "priority".

Exact endpoint arguments:

{
"endpointIds": [
"7e4fe67a-61e5-4aa5-b93a-6871b470aaef",
"59e9b6d5-d13b-4912-9e46-a1e801c1d053"
],
"scanLevel": "full"
}

Find discovered endpoint IDs with the list_endpoints or search_endpoints tools, pensar apps endpoints <appId> in the Apex CLI, or GET /apps/{appId}/endpoints in the Console API.

Exact lists use full depth and test the supplied endpoints without commit-based narrowing. Each selected application must be ready to test. Omit endpointIds to test eligible workspace applications at priority depth by default.

Invalid IDs or incompatible arguments return a tool error without expanding the requested scope.

Returns: The queued scan’s scanId, label, status, and confirmation message. Use get_scan with that ID to check completion. Failures are MCP tool errors (isError: true).

Example prompt: “Use dispatch_pentest with these two discovered endpoint IDs only: 7e4fe67a-61e5-4aa5-b93a-6871b470aaef and 59e9b6d5-d13b-4912-9e46-a1e801c1d053. Then check the returned scan ID until it completes.”

Issues

List security issues with optional filtering.

Parameters:

ParameterTypeRequiredDescription
scanIdstringNoFilter by scan ID
statusstringNoFilter by issue status (e.g., "open", "closed")
severitystringNoFilter by severity ("critical", "high", "medium", "low")
branchstringNoFilter by git branch

Returns: A list of issues with their IDs, issueLabel references (VULN-000123), console urls, titles, severities, statuses, and file locations. Closed issues also carry closedAt, closedDisposition and duplicateOf, so a closed finding is not mistaken for a resolved one; all three are null while the issue is open.

Example prompt: “Show me all critical open issues.”

Get detailed information about a specific security issue.

Parameters:

ParameterTypeRequiredDescription
issueIdstringYesIssue UUID or label (e.g. VULN-000123) to retrieve details for

Returns: The issue object, including full CVSS, nested application, endpoint, and repository, and pullRequest (the tracked pull request URL, or null). API keys require issues:read.

Example prompt: “Give me the details on VULN-000123.”

Read a finding’s PoC, execution output, evidence steps, attack path, and source snippet at its recorded commit.

Parameters: issueId (required), an issue UUID or label in your workspace.

Returns: The evidence object, including null reasons, redaction, and truncation flags. API keys require issues:read.

Read retest attempts for a finding, newest first.

Parameters: issueId (required), an issue UUID or label in your workspace.

Returns: The retest history. API keys require issues:read. This tool reads history; it does not launch a retest.

Queue a retest against a finding’s original target. Accepts an issueId containing an issue UUID or label such as VULN-000123 in your workspace.

After a target-scope failure, pass optional targetRetry: { domainId, targetUrl } to select a verified replacement for this run. The fields and validation are shared with Retest an issue in the Console API.

OAuth sessions and API keys with issues:write can launch retests. This is a write tool, so approve the launch in your client when prompted.

Returns: issueId, sessionId, status: "queued", and a message. Queued means the request was accepted, not that the finding is fixed. View the outcome in Console or read GET /issues/{issueId}/retests through the Console API.

Example prompt: “Retest VULN-000123 against its original target.”

Update a security issue’s status, disposition, inventory endpoint association, or the pull request it tracks.

Parameters:

ParameterTypeRequiredDescription
issueIdstringYesIssue UUID or label (e.g. VULN-000123) to update
statusstringNoNew status: "open", "closed", "false-positive", or "in-review"
userFlaggedFalsePositivebooleanNoFlag the issue as a false positive
userFlaggedFalsePositiveReasonstringNoReason for flagging as false positive
closedDispositionstringNoStructured close verdict: resolved, duplicate, wont-fix, out-of-scope, risk-accepted
duplicateOfstringWith duplicateThe issue this one duplicates, as a UUID or label (e.g. VULN-000123)
closedReasonstringNoFree-text reason for closing
closedCommentsstringNoAdditional comments on closure
endpointIdstring or nullNoInventory endpoint UUID to associate. Omit to preserve the association; send null to clear endpoint and application
pullRequeststring or nullNohttp(s) URL of the pull request this finding tracks. Replaces the current link. Send null to clear it. Omit to leave it unchanged. Any provider URL is accepted

Pair closedDisposition with status: "closed" — without it the finding reads as Resolved whatever the reason says. Reopening clears it, and false-positive never carries one. other is not accepted, as it is being retired from the vocabulary.

A duplicate close must name its original in duplicateOf, another issue in the same workspace that is not itself closed as a duplicate, and no other disposition may carry one.

Endpoint updates validate workspace ownership, keep applicationId synchronized to the endpoint’s application, and reject duplicate (pentest, title, endpoint) associations.

Returns: The updated issue details, including close metadata, endpointId, applicationId, and pullRequest.

The change is also applied to the finding’s linked GitHub, Linear and Notion tickets.

Example prompt: “Close issue abc-123 as risk-accepted, we have a WAF rule in front of it.”

List the pull requests linked to a security issue, with the status of each and how it was created.

Parameters:

ParameterTypeRequiredDescription
issueIdstringYesIssue UUID or label (e.g. VULN-000123) to list pull requests for

Returns: Each pull request’s ID, URL, status, how it was created, and when. API keys require issues:read.

Fixes

List all available fixes for a security issue.

Parameters:

ParameterTypeRequiredDescription
issueIdstringYesIssue UUID or label (e.g. VULN-000123) to list fixes for

Returns: A list of fixes with their IDs and affected file paths.

Example prompt: “Are there any fixes for issue def-456?”

Get detailed information about a specific fix, including the code diff.

Parameters:

ParameterTypeRequiredDescription
fixIdstringYesFix ID to retrieve details for

Returns: The fix details including the file path, a unified diff of the changes, an explanation of what the fix does, and the related issue ID.

Example prompt: “Show me the diff for fix ghi-789.”

Agent Logs

List agent execution logs for a specific issue. Useful for understanding how the agent discovered and verified a vulnerability.

Parameters:

ParameterTypeRequiredDescription
issueIdstringYesIssue UUID or label (e.g. VULN-000123) to list logs for
levelstringNoFilter by log level: "debug", "info", "warn", "error"
rolestringNoFilter by role: "assistant", "user", "system", "tool-call", "tool-result"
limitnumberNoMaximum number of log entries to return

Returns: A list of agent log entries with timestamps, levels, roles, and content.

Example prompt: “Show me the agent logs for issue abc-123.”

Search agent execution logs by text pattern with configurable context lines.

Parameters:

ParameterTypeRequiredDescription
issueIdstringYesIssue UUID or label (e.g. VULN-000123) to search logs for
querystringYesText pattern to search for
levelstringNoFilter by log level
rolestringNoFilter by role
contextLinesnumberNoNumber of surrounding context lines to include

Returns: Matching log entries with surrounding context.

Example prompt: “Search the agent logs for issue abc-123 for mentions of SQL injection.”

List the agent execution logs from one pentest target, whether or not it produced an issue.

Parameters:

ParameterTypeRequiredDescription
targetIdstringYesPentest target ID, from list_pentest_targets
levelstringNoFilter by log level: "debug", "info", "warn", "error"
rolestringNoFilter by role: "assistant", "user", "system", "tool-call", "tool-result"
limitnumberNoMaximum number of log entries to return, 1 to 500. Defaults to 100

Returns: Log entries with their ID, timestamp, level, role, message, metadata, service, and subagent. API keys require pentests:read.

Search the agent logs of one pentest target, with surrounding context entries.

Parameters:

ParameterTypeRequiredDescription
targetIdstringYesPentest target ID, from list_pentest_targets
querystringYesText to search for in log messages. Case-insensitive
levelstringNoFilter by log level
rolestringNoFilter by role
contextLinesnumberNoNumber of surrounding entries to include, 0 to 20. Defaults to 3

Returns: Matching log entries with surrounding context. API keys require pentests:read.

Knowledge Base

Knowledge base entries are the context Pensar agents use during pentests; an entry’s priority decides when agents get it (see Knowledge Base). Entries steer what agents test and report, so the write tools need a user credential: an OAuth session can create, update, and archive entries, while a workspace API key can only read them. Creating, editing, or archiving an always entry also needs that user to be a workspace admin or owner. Every entry records the user who wrote it. Like dispatch_pentest, the write tools default to Needs approval.

List knowledge base entries, newest first.

Parameters:

ParameterTypeRequiredDescription
categorystringNofalse_positive_pattern, technology_context, testing_history, user_note, or agent_learning
statusstringNoactive, stale, or archived
tagsstring[]NoOnly entries carrying every one of these tags

Returns: Entries with their ID, title, content, category, status, priority, source, tags, createdBy, and timestamps.

Example prompt: “What does Pensar know about our tech stack?”

Get one knowledge base entry.

Parameters:

ParameterTypeRequiredDescription
idstringYesEntry UUID

Returns: The full entry.

Add a knowledge base entry, attributed to you. Requires a user credential.

Parameters:

ParameterTypeRequiredDescription
titlestringYesEntry title
contentstringYesEntry body
categorystringYesEntry category
prioritystringNoalways or on_request (default)
tagsstring[]NoTags for filtering

Returns: The created entry.

Example prompt: “Add a technology note to Pensar that our API sits behind a WAF.”

Edit a knowledge base entry. Omitted fields are unchanged; tags replaces the existing list. Requires a user credential.

Parameters:

ParameterTypeRequiredDescription
idstringYesEntry UUID
titlestringNoEntry title
contentstringNoEntry body
categorystringNoEntry category
statusstringNoactive, stale, or archived
prioritystringNoalways or on_request
tagsstring[]NoTags for filtering

Returns: The updated entry.

Archive a knowledge base entry so agents stop using it. The entry stays readable. Requires a user credential.

Parameters:

ParameterTypeRequiredDescription
idstringYesEntry UUID

Returns: The archived entry.

Applications

List the applications in your workspace, a page at a time.

Parameters:

ParameterTypeRequiredDescription
limitnumberNoApplications per page, 1 to 200. Defaults to 100
offsetnumberNoNumber of applications to skip. Defaults to 0

Returns: A page of applications with their ID, name, type, framework, and domain, plus hasMore. When hasMore is true, pass the next offset to continue. API keys require inventory:read.

Get one application with its full detail.

Parameters:

ParameterTypeRequiredDescription
appIdstringYesApplication ID

Returns: The application, including its description and disallowed actions. API keys require inventory:read.

Search applications by name and description.

Parameters:

ParameterTypeRequiredDescription
querystringYesText to match, 1 to 256 characters
typestringNoFilter by application type. An invalid value returns an error listing the allowed values
limitnumberNoApplications per page, 1 to 200. Defaults to 50
offsetnumberNoNumber of applications to skip. Defaults to 0

Returns: A page of matching applications, plus hasMore. API keys require inventory:read.

Create an application.

Parameters:

ParameterTypeRequiredDescription
namestringYesApplication name
descriptionstringYesWhat the application does
typestringNoApplication type. An invalid value returns an error listing the allowed values
frameworkstringNoFramework the application is built with
domainIdstring or nullNoID of a domain in your workspace to attach
disallowedActionsstringNoActions the testing agent must not perform

Returns: The created application. API keys require inventory:write.

Update an application. Only the fields you pass change, and at least one is required.

Parameters:

ParameterTypeRequiredDescription
appIdstringYesApplication ID
namestringNoApplication name
descriptionstringNoWhat the application does
typestring or nullNoApplication type. null clears it
frameworkstring or nullNoFramework. null clears it
domainIdstring or nullNoID of a domain in your workspace. null detaches the domain
disallowedActionsstring or nullNoActions the testing agent must not perform. null clears it

Returns: The updated application. API keys require inventory:write.

Permanently delete an application and all of its endpoints. This cannot be undone.

Parameters:

ParameterTypeRequiredDescription
appIdstringYesApplication ID

Returns: A confirmation with the deleted application’s ID. API keys require inventory:write.

Endpoints

List the endpoints of one application, a page at a time.

Parameters:

ParameterTypeRequiredDescription
appIdstringYesApplication ID
typestringNoFilter by endpoint type. An invalid value returns an error listing the allowed values
limitnumberNoEndpoints per page, 1 to 200. Defaults to 100
offsetnumberNoNumber of endpoints to skip. Defaults to 0

Returns: A page of endpoints with their ID, path, transport, type, and whether authentication is required, plus hasMore. Objectives, business logic, and the threat model are left out; read them with get_endpoint or get_endpoints. API keys require inventory:read.

Get one endpoint with its full detail.

Parameters:

ParameterTypeRequiredDescription
endpointIdstringYesEndpoint ID

Returns: The endpoint, including its description, objectives, source location, authentication details, business logic, and threat model. API keys require inventory:read.

Get the full detail of up to 100 endpoints in one call.

Parameters:

ParameterTypeRequiredDescription
endpointIdsstring[]Yes1 to 100 unique endpoint IDs

Returns: The full detail of each endpoint, in the order requested. If any ID is not found in your workspace, the call fails with a 404 error and returns none of them. API keys require inventory:read.

Search endpoints across your workspace, or within one application.

Parameters:

ParameterTypeRequiredDescription
querystringYesText to match, 1 to 256 characters
applicationIdstringNoSearch only this application. Defaults to every application in the workspace
typestringNoFilter by endpoint type. An invalid value returns an error listing the allowed values
authRequiredbooleanNoOnly endpoints that do, or do not, require authentication
limitnumberNoEndpoints per page, 1 to 200. Defaults to 50
offsetnumberNoNumber of endpoints to skip. Defaults to 0

Returns: A page of matching endpoints, plus hasMore. Like list_endpoints, it leaves out objectives, business logic, and the threat model. API keys require inventory:read.

Create a new endpoint under an application. If the application already has the same endpoint, the call returns a 409 error and changes nothing; it does not update the existing endpoint. Use update_endpoint to change it.

HTTP paths match after normalization, so case, a trailing slash, and parameter style such as :id or {id} do not matter. Other transports match on transport and exact path.

Parameters:

ParameterTypeRequiredDescription
appIdstringYesApplication to add the endpoint to
endpointstringYesEndpoint path
descriptionstringYesWhat the endpoint does
typestringNoEndpoint type. An invalid value returns an error listing the allowed values
transportstringNoTransport. An invalid value returns an error listing the allowed values
locationstringNoSource file that handles the endpoint
startLineNumbernumberNoLine in location where the endpoint’s code starts
endLineNumbernumberNoLine in location where the endpoint’s code ends
objectivesstring[]NoThe full list of testing objectives
authenticationRequiredobjectNo{ "required": boolean, "details": string }, where details is optional
businessLogicstringNoFree-text description of the endpoint’s business logic
threatModelstringNoFree-text threat model for the endpoint

Returns: The created endpoint. API keys require inventory:write.

Update an endpoint. Only the fields you pass change, and at least one is required.

Parameters:

ParameterTypeRequiredDescription
endpointIdstringYesEndpoint ID
applicationIdstringNoMove the endpoint to this application in your workspace
endpointstringNoEndpoint path
descriptionstringNoWhat the endpoint does
typestring or nullNoEndpoint type. null clears it
transportstringNoTransport
locationstring or nullNoSource file that handles the endpoint. null clears it
startLineNumbernumber or nullNoLine where the endpoint’s code starts. null clears it
endLineNumbernumber or nullNoLine where the endpoint’s code ends. null clears it
objectivesstring[]NoReplaces the whole list of testing objectives; it does not append
authenticationRequiredobject or nullNo{ "required": boolean, "details": string }. null clears it
businessLogicstring or nullNoFree-text description of the endpoint’s business logic. null clears it
threatModelstring or nullNoFree-text threat model for the endpoint. null clears it

A change that would give an application two endpoints with the same path and transport returns a 409 error.

Returns: The updated endpoint. API keys require inventory:write.

Permanently delete one endpoint. This cannot be undone.

Parameters:

ParameterTypeRequiredDescription
endpointIdstringYesEndpoint ID

Returns: A confirmation with the deleted endpoint’s ID. API keys require inventory:write.

Domains

List the domains in your workspace.

Parameters: None

Returns: The domains with their ID, URL, and verification status. API keys require inventory:read.

Add a domain to your workspace. Adding a domain does not verify it; see Verifying Domains.

Parameters:

ParameterTypeRequiredDescription
urlstringYesDomain or URL to add, e.g. app.acme.example. It is stored in canonical form

Returns: The domain, and created, which is false when the domain was already in your workspace. API keys require inventory:add.

Console API

Every MCP tool except get_endpoints has a matching Console API endpoint for programmatic access via API keys. The Console API also exposes webhook endpoints, which are not available over MCP. See the Console API for authentication and the full endpoint reference.

Usage Examples

Once connected, you can interact with Pensar through natural language in your AI coding agent. Here are some common workflows:

Run a Security Scan

Ask your agent to launch a pentest and then check the results:

“Run a Pensar pentest and let me know when it finishes.”

The agent will use dispatch_pentest to start the scan, then get_scan to poll for completion. To select exact targets, provide discovered endpoint UUIDs and ask the agent to pass them as endpointIds; omitting that field uses the workspace launch behavior described above.

Review Security Issues

Ask your agent to summarize findings from a recent scan:

“Show me all high and critical issues from my latest scan.”

The agent will use list_scans to find the most recent scan, then list_issues with severity filters to retrieve the relevant findings.

Apply a Fix

Ask your agent to retrieve and apply a recommended fix:

“Get the fix for issue abc-123 and apply it to my codebase.”

The agent will use list_fixes to find available fixes, get_fix to retrieve the diff, and then apply the patch to your local files.

Supported Clients

The Pensar MCP server works with any client that supports the Streamable HTTP transport and OAuth-based authorization. Tested clients include Claude Code, Claude Desktop, Cursor, and Windsurf.

If your preferred client is not listed above, consult its documentation on adding a remote MCP server.

Next Steps

Incidents

Use the incidents toolset to investigate Datadog alerts. API keys need incidents:read; OAuth connections use your workspace access.

  • list_incidents returns grouped alerts across all verdicts. Filter with verdict, status, or triageStatus. Pass nextCursor as cursor for the next page.
  • list_incident_events returns individual events. Set groupOf to an incident id to inspect that alert group.
  • get_incident takes incidentId and returns the full raw payload, triage analysis, evidence, indicators, recommendations, and timestamps.
  • list_incident_logs takes incidentId and returns paginated execution parts for the current triage run. Restart pagination after re-triage or to refresh active tools.
  • get_incident_log_attachment takes incidentId and partId from a log entry with hasAttachment: true. Its download URL expires after 60 seconds and provides the full content stored outside the inline log.

These tools read data. Remediation text is a recommendation to review, not approval for an agent to execute it.