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 (formerly MintMCP) 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. The route and install steps have an NTLM and a Kerberos tab, each with a plain-shares and a DFS variant; the next section says which to follow.
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, or a domain that requires Kerberos. For Kerberos you also need the hostnames of two domain controllers near the replica
Decide your setup
Two answers about your domain pick the right lines in the steps below.
- NTLM or Kerberos? NTLMv2 is the Windows default. If your domain blocks NTLM (a
Network security: Restrict NTLMpolicy, or your AD team says Kerberos only), use the Kerberos tab, which adds your domain controllers to the route and two fields to the install dialog. - Plain shares or DFS? If every share is a real server path like
\\fs01.corp.example\deals, use the Plain shares column: the route and Allowed Servers name exactly those servers. If users go through a DFS namespace like\\corp.example\files, use the DFS column: referrals send users to other servers at runtime, so the route and Allowed Servers must cover all of them.
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 the hosts and ports for your logon method:
- NTLM (default)
- Kerberos
Plain shares: list each file server.
fs01.corp.example:445
fs02.corp.example:445
DFS: allow the domain and every name under it, since referrals name servers at runtime.
corp.example:445
*.corp.example:445
Both DFS lines are needed: *.corp.example does not cover corp.example itself, and a domain-based namespace such as \\corp.example\files is reached at the domain name.
Plain shares: each file server on 445 and each domain controller on 88, where the connector gets each user's tickets. List the same controllers you will enter as Domain Controllers.
fs01.corp.example:445
fs02.corp.example:445
dc1.corp.example:88
dc2.corp.example:88
DFS: the domain and every name under it on 445, plus the controllers on 88. A domain-based namespace is resolved by asking a controller for its referral over SMB, so the controllers need 445 as well, which the wildcard covers.
corp.example:445
*.corp.example:445
dc1.corp.example:88
dc2.corp.example:88
- 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.
- Pick the authentication method and fill in the fields. The dialog shows the field names; the variable names are what you see on the connector's settings page later.
- NTLM (default)
- Kerberos
| Field | Plain shares | DFS |
|---|---|---|
Private Network Route (SMB_SOCKS5_PROXY) | the pnrte_... id you copied | same |
Shares (SMB_ROOTS) | //fs01.corp.example/deals | same, or a root like //corp.example/files |
Domain (SMB_DOMAIN) | corp.example | corp.example |
Allowed Servers (SMB_SERVERS) | the shares' own servers, fs01.corp.example | *.corp.example, or the route's exact names |
Require Encryption (SMB_REQUIRE_ENCRYPTION) | true | true |
Users enter their own Username and Password when they first connect, as alice@corp.example or CORP\alice.
| Field | Plain shares | DFS |
|---|---|---|
Authentication (SMB_AUTH) | kerberos | kerberos |
Domain Controllers (SMB_KDC) | dc1.corp.example,dc2.corp.example | same |
Private Network Route (SMB_SOCKS5_PROXY) | the pnrte_... id you copied | same |
Shares (SMB_ROOTS) | //fs01.corp.example/deals, by registered DNS name | same, or a root like //corp.example/files |
Domain (SMB_DOMAIN) | corp.example (DNS name) | corp.example (DNS name) |
Allowed Servers (SMB_SERVERS) | the shares' own servers, fs01.corp.example | *.corp.example, or the route's exact names plus a controller |
Require Encryption (SMB_REQUIRE_ENCRYPTION) | true | true |
Users enter their own Username and Password when they first connect, as alice or alice@corp.example.
Two things Kerberos is strict about: Domain has to be the DNS name, never CORP, because it names the realm; and Shares have to use the names the domain registered for the servers, normally their DNS names, because a ticket is issued for one exact name. setspn -L fs01 on a domain-joined machine lists a server's registered names. A namespace root is resolved by asking a domain controller, which is why one controller joins Allowed Servers in the DFS column.
- Click Save.
Why the domain appears both on the route and in Allowed Servers: 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' logons, 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 so lockout protection tracks each account once. With Kerberos the account must belong to the connector's domain; a username with another suffix, such as an alternate UPN suffix or a trusted domain, fails with [denied] naming the accepted forms. To run every call under one service account instead, set both as global secrets on the connector's settings page.
How Kerberos logons work
With Authentication set to kerberos, users still enter a username and password, and the connector uses them the way a Windows PC does at logon: it asks a domain controller once per tool call for the user's ticket, keeps it in a memory cache that belongs to that call alone, takes a ticket for each file server from it, and destroys the cache when the call ends. The protocol is stated rather than negotiated, so a server without a cifs/ service principal fails with [denied] saying so, where Windows would silently fall back to NTLM.
On the controller's security log each tool call is one ticket request (event 4768) and one service ticket per file server touched, rather than one logon per server. Lockout protection works as with NTLM: a wrong password is sent once, then held until the user changes it in Mintive or 30 minutes pass. A locked, disabled or expired account, an expired password, or a clock more than five minutes off the controller's is reported on every call rather than remembered, since none of those counts against the bad password count.
Not supported yet: alternate UPN suffixes, trusted domains other than the connector's own, and logons without a password (smart cards, constrained delegation).
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, or Kerberos when configured, never negotiated down. SMB3 encryption is required by default. Every call and every referral decision is logged with the tool, path and account.
- With Kerberos, the connector's generated
krb5.confis held in a sealed memory file no process can rewrite, the loopback relay to the controllers accepts connections only from the connector's own process, and the document parsers run as a separate unprivileged child that cannot reach it.
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.[denied]naming the proxy's decision for a domain controller. With Kerberos, the route lacks the controllers on port88, or on445for a domain-based namespace. Add them to the route's allowed destinations.[retry] The connector could not reach a domain controller. No controller in Domain Controllers answered. Check they are up and that the replica resolves their names and reaches88.[denied] ... has no Kerberos identity (cifs/ SPN) under that name. The share's server name is an alias without a service principal. Use the server's registered DNS name in Shares, or have an admin add the SPN withsetspn -S cifs/alias.corp.example SERVER$.[denied] ... rejected the Kerberos ticket. The file server would not accept a valid ticket, usually because its machine account password is stale or itscifs/SPN is registered to another machine. An admin should check the SPN withsetspn -Land the server's domain membership.[denied] ... is not a username this connector can log in with. With Kerberos, the username carries a suffix other than the connector's domain. Enter it asaliceoralice@corp.example.[retry] The connector's clock and the domain controller's differ. Kerberos allows five minutes of skew. Check the time on the domain controllers; the connector's own clock is Mintive's.- Startup fails naming a domain-based namespace and
SMB_SERVERS. With Kerberos, a//corp.example/...root needs a controller from Domain Controllers in Allowed Servers. Add it, or use*.corp.example.
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