Model Context Protocol (MCP) Server Setup

Pentographer includes a Model Context Protocol (MCP) server that exposes your security findings, projects, and playbooks directly to external AI agents. This allows you to perform security audits using desktop tools like Claude Desktop or Cursor. To authenticate these external tools, you must first generate a Scoped API Key.

Connection Mechanism

Because browser extensions and local AI applications run outside the server environment, they connect to the Pentographer MCP server using a secure HTTPS/SSE transport layer.

The endpoint runs at /api/mcp and requires a Scoped API key or an OAuth Bearer token to authorize requests.

Connecting Claude Desktop

To connect Claude Desktop to your Pentographer workspace, configure a remote proxy command using mcp-remote. This utility forwards local MCP queries to the Pentographer cloud server securely.

1. Open your Claude Desktop configuration file:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
2. Add pentographer to the mcpServers object:

{
  "mcpServers": {
    "pentographer": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/mcp-remote",
        "https://app.pentographer.com/api/mcp",
        "-H",
        "Authorization: Bearer ptg_your_api_key_here"
      ]
    }
  }
}

Replace ptg_your_api_key_here with a Scoped API key generated in your workspace settings.

3. Restart Claude Desktop. The hammer icon appears in the interface, indicating a successful connection.

[!NOTE] If you are self-hosting, replace https://app.pentographer.com with your own deployment URL.

Connecting Cursor IDE

To connect the Cursor IDE to your workspace:

1. Open Cursor and navigate to Settings > Features > MCP.
2. Click + Add New MCP Server.
3. Configure the settings:
   • Name: pentographer
   • Type: command
   • Command: npx -y @modelcontextprotocol/mcp-remote https://app.pentographer.com/api/mcp -H "Authorization: Bearer ptg_your_api_key_here"
4. Click Save. Cursor connects to the endpoint and lists the available tools.

[!NOTE] If you are self-hosting, replace https://app.pentographer.com with your own deployment URL.

Connecting claude.ai (Web)

The claude.ai web client supports remote MCP servers via custom connectors. Because claude.ai connects directly over HTTPS, no local proxy is required.

1. In claude.ai, open Settings > Integrations.
2. Click Add custom connector.
3. Fill in the fields:
   • Name: Pentographer
   • Remote MCP server URL: https://app.pentographer.com/api/mcp
4. Click Add. Claude will list the available Pentographer tools in the conversation interface.

Authentication is handled server-side via your Scoped API key. If your Pentographer instance is configured with OAuth, enter your OAuth Client ID and OAuth Client Secret under Advanced settings instead.

[!NOTE] If you are self-hosting, replace https://app.pentographer.com with your own deployment URL.

Available MCP Tools

Once connected, your AI assistant can invoke the following tools.

Reading Data

• list_projects: Lists all active security assessments with names, customers, and status.
• get_project: Returns scope details, dates, and associated systems for a project.
• list_findings: Lists all vulnerabilities recorded under a specific project.
• get_finding: Returns the full description, remediation steps, and version history of a finding.
• list_playbooks: Lists all test methodologies available to your organization.
• get_playbook: Returns the categories, checklist items, and template text of a specific playbook.
• list_customers: Lists all customers in your workspace.
• list_project_playbook_items: Returns the checklist progress for a specific project's playbook.

Writing Data

These tools let an AI agent log findings and update records during an active engagement:

• create_project: Creates a new security assessment with scope, dates, and customer assignment.
• create_customer: Adds a new customer to your workspace.
• create_finding: Logs a new vulnerability under a project, including title, severity, description, and remediation.
• update_finding: Edits the content of an existing finding.
• update_finding_status: Changes a finding's status (e.g., open, remediated, accepted).
• add_evidence_note: Appends a text note or observation to a finding's evidence log.
• upload_evidence: Attaches a file (screenshot, request/response, log) to a finding.
• create_playbook: Creates a new test methodology.
• create_playbook_version: Adds a new version to an existing playbook.
• publish_playbook_version: Publishes a playbook version to make it available for project assignment.
• add_playbook_category: Adds a category grouping to a playbook.
• add_playbook_item: Adds a checklist item to a playbook category.

[!CAUTION] Treat the command string and configuration files as secrets. They contain your API key. Do not check your claude_desktop_config.json file into public version control repositories.