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

  1. In your Private Network, select Add route and choose the type SOCKS5 proxy.

  2. Under Allowed destinations, enter your domain and every name under it on port 445:

    corp.example:445
    *.corp.example:445

    Both 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. To allow only specific servers instead, list each one, such as fs01.corp.example:445.

  3. Check Hosted connectors and save the route.

  4. 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. In the setup dialog, enter:
    • Private Network Route (SMB_SOCKS5_PROXY): the pnrte_... id you copied.
    • Shares (SMB_ROOTS): the whole shares users may browse, comma-separated and in forward-slash form, such as //corp.example/files or //fs01.corp.example/deals,//fs01.corp.example/legal.
    • Domain (SMB_DOMAIN): your Active Directory DNS domain, such as corp.example. DFS referrals name servers by short name, which the connector completes with it (DC1 becomes dc1.corp.example), and bare usernames become alice@corp.example.
    • Allowed Servers (SMB_SERVERS): the servers besides the shares' own that may receive users' logons, comma-separated. Enter *.corp.example for every server in the domain, or the same exact names you allowed on the route, such as corp.example,fs01,fs02. Leave it empty if your shares don't use DFS.
    • Require Encryption (SMB_REQUIRE_ENCRYPTION): keep the pre-filled true, which refuses servers without SMB3 encryption, unless a server only speaks SMB 2.x.
  4. 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.

  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, 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​

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

Next steps​