FTP Integration

The FTP integration connects MCP Express to file servers so you can move and manage files in a controlled way.

Capabilities

• Remote File Operations: Search, list, read, write, upload, and download files on FTP servers.
• Flexible Paths: Use placeholders like {{ year }} to build paths and filenames.
• Connection Validation: Verify connectivity and credentials before activating tools.

Integration

Set up FTP access so MCP Express can sign in and reach the folders you want to work with.

Connection Parameters

Configure the following fields to authorize access. Use a dedicated account with minimal privileges.

Parameter	Description	Required
Hostname	FTP server hostname or IP address.	Yes
Port	FTP port (Default: 21).	Optional
Username	Account used to sign in.	Yes
Password	Account password.	Yes

Network Access

Ensure your MCP server can reach the FTP host on the configured port and that firewalls allow access.

Connection Validation

When you test the connection, MCP Express checks that:

• Credentials Work: The username and password are accepted.
• Login Succeeds: The server allows a normal sign-in.
• Folder Access Works: The account can see its default folder.

If validation fails, the test output explains what went wrong so you can fix connectivity or permission issues.

Configuration

Once FTP access is validated, configuration defines how MCP Express exposes FTP file operations as callable tools. Most actions require a Remote Path and may optionally include filters or file content depending on the tool.

Tool Orchestration

FTP uses an action-oriented model where each tool maps to a bounded file operation. Configuration should keep path scope explicit and expose only the runtime fields needed by that action.

Action Configuration

Use action configuration to define which file operation the tool performs and which parameters are resolved at runtime. Paths and file content can include placeholders like /data/{{ year }}/{{ month }}/report.csv.

Supported Actions

The following actions are supported by the FTP integration:

• Search: Find files that match a wildcard pattern under a directory.
• Read: Read the contents of a specific remote file.
• Write: Create or update a remote file with provided content.
• Upload: Send a file to the remote server.
• Download: Fetch a remote file for downstream processing.
• List: List files and directories under a remote path.

Common Runtime Parameters

Use the following parameters according to the configured action.

Parameter	Required	Description
Action	Yes	The operation to run: search, list, read, write, upload, or download.
Remote Path	Some	Directory to search or list. Required for search and list. Also used to target a file for read, write, upload, or download.
File Content	Some	Content to write for write.
Pattern	No	Wildcard match for search (e.g., *.log).
Recursive	No	Enable subdirectory traversal for search or list.
Include Hidden	No	Include dotfiles when listing.
Max Results	No	Cap the number of returned items. Defaults: search 100, list 1000.
Encoding	No	Read mode for read: auto, text, or binary.
Overwrite	No	Overwrite existing files for write, upload, or download.

Governance Controls

Limit tools to approved base directories and avoid broad patterns in production. Keep write, upload, and download targets explicit so content is only placed where you expect it.

Test Tool Contracts Before Deployment

Use the built-in testing utility to verify placeholder resolution, required field behavior, and permissions before enabling tools in production.

Security & Patterns

This section outlines the guardrails and usage patterns that keep FTP tools safe for production. The main risks are broad path scope, overly permissive wildcard matching, oversized directory scans, and unsafe use of placeholders in paths or content.

Guardrails & Path Scope

The tool accepts Remote Path and File Content. Treat any user-provided value as untrusted until your tool configuration validates it.

Keep operations inside approved source and destination roots. That matters most for:

• search and list, which walk directory trees from a starting path.
• read, which pulls a single remote file into the model context.
• write, upload, and download, which can create or replace files on the server or MCP host.

Path Scope Must Be Enforced

Unvalidated path templates can point the connector at unintended directories or files. Enforce allowlists, root-prefix checks, and input validation before allowing runtime substitution.

FTP Pattern Semantics

The connector's search action uses filename pattern matching, not full-path regexes. The pattern field is evaluated with wildcard matching against each entry name under the chosen directory.

Common examples:

• *.log matches every file ending in .log in the current directory tree.
• report-*.csv matches files such as report-daily.csv or report-2026-05.csv.
• * matches every file name, which is useful for discovery but should be avoided in production unless the directory is tightly scoped.

The pattern only checks file names, not full folder paths. Use a specific Remote Path and a simple pattern to get more accurate results.

Action-Specific Safety

Search and List

Search and list are the main discovery operations, so they should be bounded carefully.

• Use Max Results to keep result sets small and predictable.
• Keep patterns narrow so you do not scan unnecessary files.
• Disable recursion unless the directory tree is known and stable.
• Avoid listing hidden files unless your workflow explicitly needs them.
• Recursive traversal is capped to prevent runaway scans.

Read

Read is the simplest retrieval path, but it still needs content controls.

• Prefer Encoding set to auto for mixed text files.
• Use Encoding set to text when you know the file is textual.
• Use Encoding set to binary when the file is not text and you want encoded output instead of a decode failure.

Write, Upload, and Download

These actions are where overwrites and destination selection matter most.

• Keep destination paths explicit and avoid broad placeholders.
• Use placeholders only for the variable part of a path, not the entire destination root.
• FTP servers commonly replace files on write or upload. Use Overwrite only when replacement is safe.
• Separate generation, staging, and final delivery paths so accidental replacement is easier to detect.

FTP Pattern Semantics

Use filename wildcards only. The following pattern types are supported.

Supported patterns

• *.log
• report-*.csv
• invoices-2026-??.pdf
• *

Not supported

• ^report-.*\.csv$ (regex)
• **/*.log (globstar)
• logs/(error|warn)-*.txt (regex group)
• data/2026/[01-12]/report.csv (regex-style range)

Prefer patterns like *.log or report-*.csv over *. Use a narrow Remote Path when you need precise targeting.

Performance Optimization

Pattern	Description	Benefit
Bounded Results	Keep Max Results conservative for Search and List.	Prevents oversized responses.
Targeted Patterns	Prefer patterns like *.log or report-*.csv over *.	Reduces unnecessary file matches.
Limited Recursion	Only enable recursion when the directory tree is known.	Avoids runaway traversal and slow scans.
Encoding Choices	Use the right encoding mode for each file type.	Prevents decode errors and unnecessary encoded output.
Explicit Destinations	Keep write/upload/download targets precise.	Reduces accidental overwrites and delivery mistakes.

Protocol Limitations

• Search patterns are matched against file names, so they are not a substitute for path allowlists.
• Directory listings depend on FTP server LIST formats and may omit timestamps.
• Very large files can exceed response size limits if returned inline.
• Recursive directory traversal is intentionally capped to avoid runaway scans.