docs(rfc): propose MCP client integration design

[mason5052]

Summary

Adds a single docs-only RFC at examples/proposals/mcp_client_integration.md that proposes how PentAGI could support external Model Context Protocol (MCP) servers as a first-class tool source, with Burp Suite Pro MCP as the motivating example from #296. No runtime, dependency, GraphQL/REST schema, generated, compose, or installer changes are included. The implementation work is intentionally deferred so the design can be reviewed first.

Problem

Issue #296 proposes a generic MCP client and, in its current form, leans toward auto-discovering and exposing every MCP-advertised tool to every agent by default. That direction has the same shape as the patterns pushed back on during PR #268 review: implicit lifecycle, weak operator visibility, and limited operator control over what agents can reach. Before any MCP runtime lands, a written design surface is needed so the maintainer team can push back on shape, scope, transport, and security boundaries.

Solution

Add one new proposal document under the maintainer's relocated proposals path (examples/proposals/, established in commit 47de4e4 and used by evidence_chain.md and osint-integration-scenarios.md). The RFC is structured into the following sections:

• Summary
• Goals
• Non-Goals
• Design Principles
• Proposed v1 Design
• Burp Suite MCP Example
• Security and Safety
• Observability and Auditability
• Open Questions
• Suggested First Milestone

Notable framing choices in the RFC:

• Rejects auto-trusting every advertised MCP tool, hidden background execution, hidden retry queues, arbitrary host or network access from MCP servers, a generic plugin marketplace, and any change to existing native tools.
• Carries forward lessons from PR feat: queue input for running automation flows #268 review so the design starts from explicit-by-default, allowlist-driven exposure, namespaced tool names (mcp.<server>.<tool>), bounded timeouts and payload sizes, secret redaction, and audit parity with native tools.
• Treats Burp Suite Pro MCP as illustrative only. References PortSwigger's mcp-server repo from the issue body and sketches how a host-side Burp instance could be reached from the Kali container via host.docker.internal, with active scan tools gated behind allowlist plus target scope.
• Stages a deliberately narrow first milestone: (1) this RFC, (2) read-only HTTP/SSE discovery for one configured server with admin-visible inventory, (3) allowlisted execution with audit logs and target-scope checks, and (4) a Burp-specific operator guide once the generic path is proven.

Schema, GraphQL, REST, and UI implications are explicitly deferred to a later implementation PR rather than pre-decided here.

User Impact

• Maintainers get a written design surface to react to before any runtime code lands, and can shape the namespace, allowlist, transport order, and milestone slicing in review.
• Operators evaluating PentAGI for MCP-backed tooling (Burp in particular) can see the intended posture -- disabled by default, allowlist required, audited, and staged -- and plan around that direction before any feature ships.
• No behavior change for any current PentAGI user: the PR adds documentation only.

Test Plan

• git diff --stat shows exactly one new file, examples/proposals/mcp_client_integration.md.
• git diff --check is clean (no whitespace errors).
• All 11 required H2 sections are present and ordered as listed above (plus the H1 title).
• No code, schema, GraphQL, generated, compose, Dockerfile, Makefile, installer, or other runtime files touched.
• No new dependencies introduced.
• Markdown renders cleanly (lists, fenced code, headings).
• RFC explicitly avoids any claim that MCP or Burp MCP is currently supported, implemented, or shipped; uses RFC / proposed / future / candidate language throughout.

Refs #296

[Copilot]

Pull request overview

Adds a docs-only RFC proposing a staged design for integrating external Model Context Protocol (MCP) servers as a first-class tool source in PentAGI, using Burp Suite Pro MCP as a motivating example. This is intended to set explicit-by-default boundaries (allowlists, namespacing, auditability, safety) before any runtime implementation work begins.

Changes:

• Introduces an RFC describing a proposed v1 MCP client design (configuration model, transports, discovery, namespacing, invocation/audit semantics).
• Includes an illustrative Burp Suite MCP setup example plus security/observability considerations and open questions.
• Proposes a narrow, reviewable first milestone sequence (discovery → allowlisted execution → Burp operator guide).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.