PUMA Vault

MCP — Model Context Protocol: Architecture, Security, and PUMA Integration

Se lee en 4 min

PN: MCP — Model Context Protocol: Architecture, Security, and PUMA Integration

Core Idea

The Model Context Protocol (MCP) is an open standard (Anthropic, Nov 2024) that defines how LLM agents connect to external tools, data sources, and services through a unified client–server interface. MCP replaces ad-hoc API integrations with a structured protocol, enabling any MCP-compatible agent to use any MCP server without custom connectors.

What MCP Solves

Before MCP, each tool integration required custom code: a Jira agent needed a Jira client, a GitHub agent needed a GitHub client, and combining them required manual orchestration. This produced:

  • Fragmented, non-interoperable tool stacks
  • Inconsistent error handling and authentication
  • Repeated plumbing code across agent frameworks

MCP provides: one protocol, any tool.

Architecture

Three-Layer Model

┌──────────────────────────────────────────────────────────┐
│                    MCP HOST                               │
│   (LLM application — Claude Desktop, Claude Code, PUMA)  │
│                                                           │
│   ┌─────────────┐     ┌─────────────┐                   │
│   │ MCP Client  │     │ MCP Client  │                   │
│   │  (Jira)     │     │  (GitHub)   │                   │
│   └──────┬──────┘     └──────┬──────┘                   │
└──────────┼───────────────────┼──────────────────────────┘
           │  JSON-RPC 2.0     │  JSON-RPC 2.0
           │  (stdio / SSE)    │
   ┌───────▼──────┐    ┌───────▼──────┐
   │  MCP Server  │    │  MCP Server  │
   │  jira-server │    │ github-server│
   └──────────────┘    └──────────────┘
  • MCP Host: the AI application that orchestrates agent behaviour
  • MCP Client: one client instance per server, lives inside the host
  • MCP Server: lightweight process exposing tools, resources, or prompts

Transport Protocols

TransportUse CaseNotes
stdioLocal servers (same machine)Default for local tools
SSE (Server-Sent Events)Remote / cloud serversHTTP-based, stateful
Streamable HTTPStateless remote servers2025 spec addition

Core Primitives

PrimitiveDescriptionExample
ToolsCallable functions (agent-invoked)create_jira_issue, get_pr_diff
ResourcesData sources (context-window read)file://project-docs, db://tawos
PromptsReusable prompt templatestriage-issue-template
SamplingServer-initiated LLM requestsModel-controlled chaining

Security Threat Taxonomy (Hou et al., 2025)

MCP Security Risks

The open nature of MCP creates a new attack surface. Any MCP server can request tool calls or inject content into the agent’s context.

Threat Categories

ThreatDescriptionPUMA Mitigation
Prompt InjectionMalicious tool output overwrites system instructionsSanitise tool outputs before context injection
Tool PoisoningMalicious MCP server registers harmful toolsTool allowlist in OPA policy
Rug PullServer behaviour changes after approvalPin server versions; audit on update
Data ExfiltrationTool silently sends data to external endpointsNetwork egress rules; airgap local servers
Privilege EscalationTool requests more permissions than declaredExplicit capability manifests; minimal grant
TOCTOUTool output changes between observation and executionAtomic tool-use sequences

Defence Layers

Layer 1: Tool Allowlist     → only declared tools can be called
Layer 2: Capability Manifest → tools declare max permissions at registration
Layer 3: OPA Policy Engine  → per-call authorisation (bounded autonomy)
Layer 4: Output Sanitisation → tool outputs scanned before context injection
Layer 5: Audit Log          → all tool calls logged for post-hoc review

MCP in PUMA Stage 5 (Smart PMO)

PUMA’s Stage 5 agent uses MCP to connect to:

MCP ServerToolsPurpose
jira-mcp-serverget_issue, create_issue, update_priority, add_commentJira triage + prioritisation execution
github-mcp-serverget_pr, list_issues, get_repo_statsCodebase context for issue enrichment
tawos-mcp-serverquery_historical, get_similar_issuesIn-context few-shot retrieval from TAWOS

PUMA Governance Layer (Constitution Article 4)

# OPA policy: bounded autonomy gate for Jira write operations
allow if {
    input.tool == "update_priority"
    input.confidence >= 0.85      # agent certainty threshold
    input.change.priority_delta <= 1  # max 1 level change per call
    input.hitl_approved == true   # human confirmed if confidence < 0.95
}
 
deny if {
    input.tool in {"delete_issue", "close_sprint"}  # destructive ops blocked
}

Context Window Impact

MCP tool definitions consume token budget. PUMA profile:

ComponentTokens (approx.)
Tool schemas (3 servers × 4 tools)~1,200
Tool result per call500–3,000
Active tool call overhead200

For PUMA’s 32k local model context: tool schemas ~4% overhead, manageable.

MCP vs. Alternative Integration Approaches

ApproachProsCons
MCPStandard protocol; interoperable; security primitives built-inRequires MCP server for each tool
REST API directFull control; no extra layerCustom code per integration; no standard security model
LangChain ToolsRich ecosystem; Python nativeFramework lock-in; not interoperable outside Python
Function Calling (OpenAI style)Widely supportedStateless; no resource or prompt primitives

MCP is the most future-proof choice for PUMA’s multi-tool Stage 5 architecture.

Implementation Notes for PUMA

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
 
async def create_puma_mcp_session():
    server_params = StdioServerParameters(
        command="python",
        args=["-m", "jira_mcp_server"],
        env={"JIRA_URL": os.getenv("JIRA_URL"),
             "JIRA_TOKEN": os.getenv("JIRA_TOKEN")}
    )
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()  # discovery
            return session, tools

Key considerations:

  • MCP sessions are stateful; maintain one session per server across agent lifetime
  • Use list_tools() at startup for dynamic tool discovery
  • Handle McpError responses from tool calls — surface as Reflexion critique material

MOCs

Vista Gráfica

Retroenlaces