# crewai-mcps

Cryptographic security layer for CrewAI MCP tool calls.

`crewai-mcps` adds message signing, nonce-based replay protection, and tool definition pinning to CrewAI's Model Context Protocol (MCP) integrations. It addresses specific risks from the [OWASP MCP Top 10](https://owasp.org/www-project-mcp-top-10/):

| OWASP MCP Risk | Coverage | What crewai-mcps does |
|---|---|---|
| **MCP-01: Tool Poisoning** | Full | Pins tool definitions at discovery; blocks execution if definition changes |
| **MCP-04: Tool Rug Pulls** | Full | Hashes tool schemas on first contact; any mutation raises `ToolIntegrityError` |
| **MCP-08: Logging Gaps** | Full | Structured audit trail with sequence numbers, timestamps, and exportable JSON |
| **MCP-10: Lack of Integrity** | Full | Cryptographic signatures on canonical JSON payloads; tampered arguments fail verification |
| **Replay Attacks** | Full | Every call carries a unique nonce with configurable TTL; duplicates are rejected |

MCP-02 (permissions), MCP-06 (resource injection), MCP-07 (auth), and MCP-09 (resource abuse) are outside the scope of this package -- they require policy-layer enforcement. See [ELIDA](https://github.com/zamorofthat/elida) for behavioural-layer coverage of all 10.

## Installation

```bash
pip install crewai-mcps
```

With CrewAI:
```bash
pip install 'crewai-mcps[crewai]'
```

## Quick Start

### Wrap MCP tools (recommended)

```python
from crewai import Agent, Task, Crew
from crewai.mcp import MCPServerAdapter
from crewai_mcps import SecureMCPTool, AuditTrail

# Optional: audit trail for compliance
audit = AuditTrail()

# Zero config -- keys generated automatically
secure = SecureMCPTool(audit_trail=audit)

server_params = {
    "url": "http://localhost:8001/mcp",
    "transport": "streamable-http",
}

with MCPServerAdapter(server_params) as tools:
    # One line to add security
    secured_tools = secure.wrap_tools(tools)

    agent = Agent(
        role="Analyst",
        goal="Perform secure analysis",
        backstory="All tool calls are cryptographically signed.",
        tools=secured_tools,
    )

    task = Task(
        description="List available files.",
        expected_output="A file listing.",
        agent=agent,
    )

    crew = Crew(agents=[agent], tasks=[task])
    result = crew.kickoff()

# Review what happened
print(audit.summary())
audit.export_json("audit.json")
```

### Global hooks (signs all tool calls)

```python
from crewai_mcps import SecureMCPTool, install_crewai_hooks

secure = SecureMCPTool()
cleanup = install_crewai_hooks(secure)

# All tool calls are now signed automatically
# ... run your crew ...

cleanup()  # Remove hooks when done
```

## Features

### Cryptographic Signing

Every tool call is signed with an automatically generated key pair. The signature covers the canonical JSON of the tool name, arguments, nonce, and timestamp. Any tampering with the arguments invalidates the signature.

```python
secure = SecureMCPTool()

# Sign a call manually
envelope = secure.sign_call("search", {"query": "test"})
# => {'nonce': '...', 'timestamp': '...', 'signature': '...', 'tool_name': 'search'}
```

### Replay Protection

Each call carries a unique nonce. The `NonceTracker` maintains a time-windowed set of used nonces (default: 5 minutes). Duplicate nonces are rejected.

```python
from crewai_mcps import NonceTracker

tracker = NonceTracker(max_age_seconds=300)
nonce = tracker.generate()

# First use: OK
tracker.check_and_consume(nonce)  # True

# Replay attempt: blocked
tracker.check_and_consume(nonce)  # False
```

### Tool Pinning (Rug-Pull Detection)

When tools are discovered from an MCP server, their definitions (name, description, schema) are hashed and pinned. If the server changes a tool's definition between calls, execution is blocked with a `ToolIntegrityError`.

```python
from crewai_mcps import ToolPinner

pinner = ToolPinner()
pinner.pin("write_file", {
    "name": "write_file",
    "description": "Write a file to disk",
    "schema": {"type": "object", "properties": {"path": {"type": "string"}}},
})

# Later: server changes the tool
pinner.verify("write_file", {
    "name": "write_file",
    "description": "Write a file to disk",
    "schema": {
        "type": "object",
        "properties": {
            "path": {"type": "string"},
            "exec_cmd": {"type": "string"},  # Injected!
        },
    },
})
# => False
```

### Structured Audit Trail

Every signed call, response, error, and security event is recorded with monotonically increasing sequence numbers. Export the full trail for compliance.

```python
from crewai_mcps import AuditTrail

audit = AuditTrail(max_events=10000)

# Events are recorded automatically when used with SecureMCPTool
secure = SecureMCPTool(audit_trail=audit)

# Query the trail
audit.get_events_for_tool("search")
audit.get_security_alerts()
audit.get_errors()

# Export
audit.export_json("trail.json")
print(audit.summary())
```

### Response Verification

Standalone verifier for matching responses to signed requests with timing checks.

```python
from crewai_mcps import ResponseVerifier

verifier = ResponseVerifier(max_response_age=30.0)
verifier.register_request("nonce-1", "search", {"q": "test"}, envelope)

# Later...
result = verifier.verify_response("nonce-1", "search", response)
if result.valid:
    print("Response verified")
else:
    print(f"Verification failed: {result.errors}")
```

## Architecture

```
CrewAI Agent
    |
    v
SecureToolProxy (wraps each MCP tool)
    |
    +-- ToolPinner.verify()     # Check definition integrity
    +-- SecureMCPTool.sign()    # Sign with nonce + timestamp
    +-- original_tool.run()     # Execute the real tool
    +-- verify_response()       # Log and verify result
    +-- AuditTrail.log()        # Record everything
```

## API Reference

| Class | Purpose |
|---|---|
| `SecureMCPTool` | Main entry point. Wraps tools, signs calls, verifies responses |
| `SecureToolProxy` | Transparent proxy that intercepts tool execution |
| `KeyManager` | Manages cryptographic key pairs |
| `NonceTracker` | Generates and validates nonces with TTL |
| `ToolPinner` | Hashes and pins tool definitions |
| `ResponseVerifier` | Matches responses to requests with timing checks |
| `AuditTrail` | Thread-safe structured event log |
| `install_crewai_hooks` | Registers MCPS as global CrewAI tool hooks |

## Requirements

- Python 3.10+
- `cryptography` >= 41.0
- `crewai` >= 0.80.0 (optional, for hook integration)

## License

Apache 2.0. See [LICENSE](LICENSE).
