Set up the SMB File Share MCP server
The SMB File Share MCP server gives AI agents read-only access to documents on Windows file servers, NAS devices and DFS namespaces: browsing folders, finding files by name, and reading PDF, Word and text documents. Every tool call logs in to the file server with the calling user's own Active Directory account, so people see exactly what they would see in Explorer.
The connector runs in Mintive and reaches your file servers through a Private Network. This guide covers preparing the network, creating its SOCKS5 route, installing the connector from the Mintive store, and moving it into the network.
Prerequisites
- A Mintive admin account
- A Private Network with a connection replica on a host that can reach your file servers on port
445 - The UNC paths of the shares to expose, for example
\\corp.example\filesor\\fs01.corp.example\deals - File servers that accept NTLMv2 with SMB signing, which is the Windows default. Kerberos-only domains are not supported
Prepare the Private Network
The replica looks up each file server by name, so it needs to be on agent version 0.2.0 or later, which serves SOCKS5 routes, and its host's DNS must resolve your Active Directory domain. With Docker, point the replica's container at a domain controller with --dns, for example --dns 10.0.0.10. A domain controller answers for the domain and forwards everything else.
On the Private Network page, confirm the replica is Ready and its runtime is Connected.
Create the SOCKS5 route
The connector reaches every file server through one route that the replica serves as a SOCKS5 proxy. DFS referrals name servers at runtime, and the replica resolves each one, so a server added to the namespace later works without a new route.
-
In your Private Network, select Add route and choose the type SOCKS5 proxy.
-
Under Allowed destinations, enter your domain and every name under it on port
445:corp.example:445*.corp.example:445Both lines are needed:
*.corp.exampledoes not covercorp.exampleitself, and a domain-based namespace such as\\corp.example\filesis reached at the domain name. To allow only specific servers instead, list each one, such asfs01.corp.example:445. -
Check Hosted connectors and save the route.
-
Copy the route's
pnrte_...id.
Add SMB File Share to Mintive
- In Mintive, go to MCP store > Manage store.
- Find SMB File Share in the Catalog tab and click to install it.
- In the setup dialog, enter:
- Private Network Route (
SMB_SOCKS5_PROXY): thepnrte_...id you copied. - Shares (
SMB_ROOTS): the whole shares users may browse, comma-separated and in forward-slash form, such as//corp.example/filesor//fs01.corp.example/deals,//fs01.corp.example/legal. - Domain (
SMB_DOMAIN): your Active Directory DNS domain, such ascorp.example. DFS referrals name servers by short name, which the connector completes with it (DC1becomesdc1.corp.example), and bare usernames becomealice@corp.example. - Allowed Servers (
SMB_SERVERS): the servers besides the shares' own that may receive users' logons, comma-separated. Enter*.corp.examplefor every server in the domain, or the same exact names you allowed on the route, such ascorp.example,fs01,fs02. Leave it empty if your shares don't use DFS. - Require Encryption (
SMB_REQUIRE_ENCRYPTION): keep the pre-filledtrue, which refuses servers without SMB3 encryption, unless a server only speaks SMB 2.x.
- Private Network Route (
- Click Save.
The domain appears both on the route and in Allowed Servers on purpose. The route decides which hosts any hosted connector on the network may reach, while Allowed Servers decides which servers may receive this connector's users' passwords, and is checked before each logon. A server has to pass both.
Move the connector into the Private Network
A connector installed from the store starts outside any network. It runs, but until it is moved every tool call fails with [denied] saying the connector is not in a Private Network yet.
- Open the connector's settings page, click the Hosted connector tab, and expand Networking.
- Select your network in Move to another network and click Move connector.
Connect as a user
Each user enters their own Username (SMB_USERNAME) and Password (SMB_PASSWORD) the first time they call an SMB File Share tool. Ask your team to use one spelling, either alice@corp.example or CORP\alice, so lockout protection tracks each account once. To run every call under one service account instead, set both as global secrets on the connector's settings page.
What the connector exposes
| Tool | What users can do |
|---|---|
list_directory | List a folder, folders first. Without a path, see the allowed roots |
search_files | Find files and folders by name under a folder, with optional extension filter and depth. Names only, within a 20 second and 5,000 folder budget, so results carry truncated and a hint |
read_document | Read PDF, DOCX and plain-text files (txt, md, csv, tsv, json, xml, html, htm, log) a range of pages or sections at a time. Scanned PDF pages are listed in empty_units |
Security considerations
- Every call logs in as the calling user, so the file server's own share and NTFS permissions decide what each person can read, and the server's audit log shows the real account. No session or password is kept between calls, so one user can never ride another's logon.
- Each call is a domain logon, and lockout policies count failures. A rejected password is sent once, then not retried until the user changes it in Mintive or 30 minutes pass.
- The connector never follows a DFS referral to a server outside
SMB_SERVERSand never opens a share outsideSMB_ROOTSor one a referral named on an allowed server, so credentials go nowhere you did not list. - Roots are whole shares on purpose. Symbolic links inside a share can point anywhere in that share, so restrict folders with the file server's permissions rather than the allowlist.
- With a wildcard, anyone who can edit a DFS link can point it at any server in the domain, and the next user to browse there sends it their NTLM logon, as a mapped drive would. SMB signing stops the logon being relayed, not the server capturing it. Listing exact server names on the route and in
SMB_SERVERSprevents this. - Logons are NTLMv2 with signing required, and SMB3 encryption is required by default. Every call and every referral decision is logged with the tool, path and account.
Troubleshooting
[retry] Could not reach the file server. The replica or the server is down, or the replica could not resolve the server's name. Check the replica on the Private Network page, where a failed lookup shows asRoute connection failing: resolve ..., and that the server answers on 445 from the replica's host.[denied]naming the proxy's decision. The route's allowed destinations do not include that server. Add it to the route, or check that both the domain and*.lines are there.[denied] DFS sends ... to a server that is not in SMB_SERVERS. The namespace referred to a server outside your server list. The message names it; add it toSMB_SERVERSand the route.- One user gets
[denied]on a folder others can read. That is the file server's answer for their account. Check the folder's permissions on the server. - Every call fails with
[denied]after a password change. The user must updateSMB_PASSWORDin Mintive. The connector stops retrying a rejected password to keep the account from locking out. does not support SMB encryption. The server only speaks SMB 2.x. SetSMB_REQUIRE_ENCRYPTION=falseif signed but unencrypted traffic to it is acceptable.
Next steps
- Private Networks: Run the connection replica and manage routes
- Tool customization: Control which SMB File Share tools are exposed to users
- MCP gateway administration: Manage access and permissions