Filesystem Access¶

The MCP Guide server can request access to files and directories on the agent's filesystem to provide contextual assistance with your projects.

What It Does¶

The filesystem access feature allows the MCP server to: - Read file contents to understand your codebase - List directory contents to discover project structure - Detect project types and configurations - Cache frequently accessed files for better performance

This enables more accurate and contextual assistance by understanding your actual project files rather than working from general knowledge alone.

Security Model¶

By default, filesystem access is restricted to protect your system.

Multi-Layer Security Architecture¶

The filesystem access system implements defence-in-depth with multiple security layers:

Path Validation Layer
Normalises all paths to prevent traversal attacks
Validates against allowed path prefixes
Blocks access to system and sensitive directories
Resolves and validates symbolic links
Security Policy Layer
Enforces read/write permissions per project
Maintains audit logs of all access attempts
Tracks security violations and blocked requests
Provides configurable security levels
Sampling Request Layer
Agent-side validation before file operations
Secure communication between server and agent
Fallback handling for unsupported operations
Error recovery and retry mechanisms

Default Security Restrictions¶

Read Access: Limited to project directories (src/, docs/, tests/, etc.)
Write Access: Restricted to explicitly configured paths only
System Protection: No access to system directories (/etc, /usr, /System)
Privacy Protection: No access to sensitive directories (~/.ssh, ~/.aws, etc.)
Attack Prevention: Path traversal attacks (../../../etc/passwd) are blocked
Link Validation: Symbolic links are resolved and validated to prevent escaping

Security Audit and Monitoring¶

All filesystem access attempts are comprehensively logged with: - Requested path and operation type (read/write/list) - Success/failure status and error details - Security violations and blocked attempts - Timestamp, user context, and request source - Performance metrics and cache statistics

Audit logs are structured for easy analysis and can be integrated with security monitoring systems.

Configuration¶

Project-Level Path Configuration¶

Configure allowed paths in your project's .guide.yaml:

allowed_write_paths:
  - src/
  - docs/
  - tests/
  - config/
  - config.json

additional_read_paths:
  - /absolute/path/to/external/libs
  - /home/user/vendor

Configuration Options¶

`allowed_write_paths` (Array of strings)¶

Purpose: Files or directories where the MCP server can write
Default: [] (empty - no writes allowed by default)
Security: Paths are validated and normalized
Format: Relative paths from project root
Directories: End with / (e.g., src/, docs/)
Files: No trailing slash (e.g., config.json, .guide.yaml)

`additional_read_paths` (Array of strings)¶

Purpose: Additional absolute paths for read-only access
Default: [] (empty)
Use Cases: External dependencies, build outputs, external libraries
Security: Read-only access, must be absolute paths, system directories blocked
Format: Absolute paths (e.g., /home/user/data, /opt/external)

Managing Paths via Commands¶

Use the built-in guide commands to safely manage paths:

# View current permissions
@guide :project/perm

# Add write permissions
@guide :project/perm/write/add src/
@guide :project/perm/write/add config.json

# Remove write permissions
@guide :project/perm/write/remove src/

# Add read permissions (absolute paths)
@guide :project/perm/read/add /external/data

# Remove read permissions
@guide :project/perm/read/remove /external/data

These commands automatically: - Validate path format and security - Update your project configuration in .guide.yaml - Apply changes immediately - Prevent system directory access

Advanced Security Configuration¶

Removing Restrictions (Use with Caution)¶

If you need unrestricted filesystem access and fully trust this MCP server:

kiro-cli /tools trust-all

⚠️ WARNING: This removes all security restrictions. The MCP server will have access to your entire filesystem. Only use this if you: - Completely trust this MCP server - Understand the security implications - Are working in an isolated/sandboxed environment

To restore restrictions:

kiro-cli /tools trust-all false

Architecture Overview¶

Component Interaction¶

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Server    │───▶│  Sampling API    │───▶│   Agent (CLI)   │
│                 │    │                  │    │                 │
│ • Path requests │    │ • Security check │    │ • File access   │
│ • Content proc. │    │ • Audit logging  │    │ • Response send │
│ • Cache mgmt.   │    │ • Error handling │    │ • Local validation│
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   File Cache    │    │ Security Policy  │    │ Path Validator  │
│                 │    │                  │    │                 │
│ • LRU eviction  │    │ • Path rules     │    │ • Normalization │
│ • Size limits   │    │ • Audit trail    │    │ • Symlink check │
│ • TTL tracking  │    │ • Violation log  │    │ • Traversal block│
└─────────────────┘    └──────────────────┘    └─────────────────┘

Data Flow¶

Request: MCP server requests file/directory access
Validation: Security policy validates path against allowed lists
Sampling: Secure sampling request sent to agent
Agent Processing: Agent validates and performs file operation
Response: File content/listing sent back to server
Caching: Results cached with modification time tracking
Audit: All operations logged for security monitoring

How It Works¶

File Access Process¶

Path Request: MCP server requests access to a specific file or directory
Security Validation:
Path normalised and validated against security policy
Checked against allowed_write_paths and additional_read_paths
System and sensitive directories blocked
Cache Check: Recently accessed files served from cache if still valid
Sampling Request: If not cached, secure request sent to agent
Agent Validation: Agent performs additional security checks
File Operation: Agent reads file/directory and sends response
Caching: Response cached with modification time for future requests
Audit Logging: Complete operation logged for security monitoring

Performance Optimisations¶

Intelligent Caching: LRU cache with size and entry limits
Modification Tracking: Files re-read only when modified
Batch Operations: Multiple file requests optimised
Compression: Large responses compressed for network efficiency

Privacy Considerations¶

Explicit Access: File contents only accessed when specifically requested
No Scanning: No automatic scanning or indexing of your filesystem
Temporary Caching: Cached contents stored temporarily with TTL
Modification Respect: Cache invalidated when files change
Complete Logging: All access attempts logged and auditable
User Control: Full control over accessible paths and security level
Opt-in Model: Filesystem access requires explicit configuration

Troubleshooting¶

Common Issues¶

Access Denied Errors - Check if path is in allowed_write_paths or additional_read_paths - Verify path format: - Write paths: Relative, directories end with /, files without - Read paths: Absolute paths only - Review audit logs for security violations

Performance Issues - Monitor cache hit rates in statistics - Adjust cache size limits if needed - Check for excessive file modification causing cache misses

Configuration Problems - Validate YAML syntax in .guide.yaml - Use @guide :project/perm to verify current settings - Check file permissions on configuration file

The filesystem access feature is designed to be helpful while maintaining security by default. You can always restrict access further or remove restrictions entirely based on your specific needs and trust level.