Skip to main content
Mintive is the new name for MintMCP.Read the announcement

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\files or \\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 NTLM policy, 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.

  1. In your Private Network, select Add route and choose the type SOCKS5 proxy.
  2. Under Allowed destinations, enter the hosts and ports for your logon method:

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.

  1. Check Hosted connectors and save the route.
  2. Copy the route's pnrte_... id.

Add SMB File Share to Mintive​

  1. In Mintive, go to MCP store > Manage store.
  2. Find SMB File Share in the Catalog tab and click to install it.
  3. 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.
FieldPlain sharesDFS
Private Network Route (SMB_SOCKS5_PROXY)the pnrte_... id you copiedsame
Shares (SMB_ROOTS)//fs01.corp.example/dealssame, or a root like //corp.example/files
Domain (SMB_DOMAIN)corp.examplecorp.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)truetrue

Users enter their own Username and Password when they first connect, as alice@corp.example or CORP\alice.

  1. 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.

  1. Open the connector's settings page, click the Hosted connector tab, and expand Networking.
  2. 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​

ToolWhat users can do
list_directoryList a folder, folders first. Without a path, see the allowed roots
search_filesFind 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_documentRead 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_SERVERS and never opens a share outside SMB_ROOTS or 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_SERVERS prevents 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.conf is 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 as Route 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 to SMB_SERVERS and 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 update SMB_PASSWORD in 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. Set SMB_REQUIRE_ENCRYPTION=false if 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 port 88, or on 445 for 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 reaches 88.
  • [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 with setspn -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 its cifs/ SPN is registered to another machine. An admin should check the SPN with setspn -L and 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 as alice or alice@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​