Example: Filesystem MCP Server

Connect OpalServe to access local files and directories. The filesystem server is one of the most commonly used MCP servers and a great starting point.

Setup

opalserve server add \
  --name files \
  --stdio "npx -y @modelcontextprotocol/server-filesystem /path/to/your/project" \
  --description "Project filesystem access" \
  --tags files,local

Replace /path/to/your/project with the directory you want to expose to AI tools.

Path access

The filesystem server only allows access within the specified directory and its subdirectories. It cannot access parent directories or other parts of your filesystem.

Available Tools

Tool	Description
read_file	Read the contents of a file
write_file	Create or overwrite a file
list_directory	List files and subdirectories
create_directory	Create a new directory
move_file	Move or rename a file/directory
search_files	Search for files by name pattern
get_file_info	Get file metadata (size, dates, permissions)
read_multiple_files	Read several files in a single call

Verification

opalserve tools list --server files
opalserve tools search "read"

Multiple Directories

Register separate servers for different directories:

opalserve server add \
  --name docs \
  --stdio "npx -y @modelcontextprotocol/server-filesystem /home/user/docs" \
  --description "Documentation" \
  --tags docs,files

opalserve server add \
  --name code \
  --stdio "npx -y @modelcontextprotocol/server-filesystem /home/user/projects" \
  --description "Source code" \
  --tags code,files

opalserve server add \
  --name config \
  --stdio "npx -y @modelcontextprotocol/server-filesystem /etc/app-configs" \
  --description "Application configs" \
  --tags config,files

Search across all filesystem servers at once:

opalserve tools search "read file"
# Returns tools from docs, code, and config servers

Team Mode

In team mode, the admin can expose shared directories to the entire team. This is useful for:

• Shared documentation — team wikis, runbooks, architecture docs
• Configuration templates — shared config files and examples
• Shared assets — design files, scripts, templates

# Admin registers on the team server
opalserve server add \
  --name shared-docs \
  --stdio "npx -y @modelcontextprotocol/server-filesystem /opt/team-docs" \
  --description "Team documentation" \
  --tags docs,shared

# Team members sync and use
opalserve sync
opalserve tools search "read"

Knowledge Base vs Filesystem Server

For team documentation that AI tools should reference frequently, consider using the knowledge base instead. It provides chunked indexing and relevance-ranked search, which is more efficient for large documentation sets. Use the filesystem server when AI tools need to read/write actual files.

HTTP API Usage

# Read a file
curl -X POST "http://localhost:3456/api/v1/tools/files%3Aread_file/call" \
  -H "Content-Type: application/json" \
  -d '{"path": "README.md"}'

# List a directory
curl -X POST "http://localhost:3456/api/v1/tools/files%3Alist_directory/call" \
  -H "Content-Type: application/json" \
  -d '{"path": "src/"}'

# Search for files
curl -X POST "http://localhost:3456/api/v1/tools/files%3Asearch_files/call" \
  -H "Content-Type: application/json" \
  -d '{"path": ".", "pattern": "*.ts"}'