Overview
Custom MCP Servers let you connect your own external tools and services to Hatz using the Model Context Protocol (MCP) standard. Once connected, the tools exposed by your MCP server become available for use directly in Hatz chat - just like built-in integrations.
This is useful when you have internal tools, proprietary APIs, or third-party MCP-compatible services that aren't part of the standard Hatz integrations catalog.
HTTP MCP Servers Only
Hatz AI only supports HTTP-based MCP servers. Customers must host and maintain these servers on their own infrastructure. Hatz does not provide support for server implementation, hosting, or deployment. Support is limited to connectivity and integration issues within the Hatz platform only.
Who this is for
Custom MCP Servers are designed for:
Technical users or workspace admins who manage integrations
Teams with internal tools or proprietary APIs they want to connect to Hatz
Organizations using MCP-compatible third-party services
Users who want to extend Hatz beyond the standard integrations catalog
Prerequisites
Before you can add a custom MCP server, you'll need:
A publicly accessible MCP server that implements the Model Context Protocol specification
Your MCP server must support Streamable HTTP transport (the recommended MCP transport for remote servers)
Admin or appropriate role permissions to manage connections in Hatz (if applicable to your organization)
Custom MCP Servers feature must be enabled for your account (contact your administrator if you don't see the feature)
Getting Started
Where to find it
Navigate to Workshop > Connections.
If enabled for your account, you'll see two tabs at the top of the page:
Hatz Integrations - the standard integrations catalog
Custom MCP Servers - where you manage your own MCP servers
Adding a custom MCP server
Click the Custom MCP Servers tab.
Click Add Server (top-right corner, or the button in the empty state).
Fill in the form:
Field | Required | Description |
Name | Yes | A display name for this server (e.g., "Internal Knowledge Base"). |
Description | No | A short description of what this server does. |
Server URL | Yes | The full URL of your MCP server endpoint (e.g., |
Authentication Method | Yes | How Hatz should authenticate with your server (see Authentication Methods below). |
(Recommended) Click the Test button next to the URL field to verify the server is reachable before saving.
Click Add Server.
Expected result: Hatz will validate the URL, test the connection, and securely store your credentials. The server will appear in your list with a status badge (typically "Connected" if successful, or "Unreachable" or "Auth Failed" if there's an issue).
Authentication Methods
When adding a server, choose the authentication method that matches your MCP server's requirements:
Method | When to use | What you provide |
None | The server requires no authentication. | Nothing additional. |
API Key | The server expects an API key in a request header. | An API key value and optionally a Header Name (defaults to |
Bearer Token | The server expects a bearer token in the | A Bearer Token value. |
OAuth |
| - |
Security note: Your credentials are encrypted and stored securely. They are never displayed after saving. When editing a server, leave credential fields empty to keep your existing credentials unchanged.
Managing Your Servers
Each server in your list shows:
Name and URL
Status badge indicating the current connection state
Tool count (if tools have been discovered)
Status badges
Badge | Meaning |
Connected (green) | The server is reachable and working. |
Unreachable (red) | Hatz can't reach the server URL. Check that the server is running and the URL is correct. |
Auth Failed (yellow) | The server is reachable, but authentication failed. Update your credentials. |
Pending (gray) | The server was just added and hasn't been tested yet. |
Server actions
Click the three-dot menu on any server card to access:
Action | What it does |
Test Connection | Pings the server URL to check if it's reachable. |
Discover Tools | Connects to your MCP server and retrieves the list of tools it exposes. This is how Hatz learns what your server can do. |
Edit | Opens the edit dialog to update the server name, description, URL, or credentials. |
Delete | Permanently removes the server and its stored credentials. |
Viewing discovered tools
After running Discover Tools, the server card will show a tool count (e.g., "3/3 tools"). Click it to expand the card and see the names of all discovered tools as badges.
Expected result: If your MCP server is properly configured and has tools available, you should see a positive tool count (e.g., "3 tools"). If you see "0 tools," your server may not be implementing the tools/list method correctly.
Using Custom MCP Tools in Chat
Once a server is connected and tools have been discovered, you can select it as a tool in chat:
Open the tool picker in a chat or workflow.
Your custom MCP servers appear alongside the built-in tools.
Each server card shows the server name, tool count, and description (or URL).
Click a server to select or deselect it.
Requirements for a server to appear in the tool picker:
The server must be enabled
The server status must be Connected (active)
The server must have at least one discovered tool
Note: You can search custom MCP servers by name, description, or URL in the tool picker.
Troubleshooting
Problem | What to try |
Server shows Unreachable | Verify the URL is correct and the server is running. Use Test Connection to re-check. Make sure the server is accessible from the internet (not behind a firewall or VPN that blocks inbound traffic). |
Server shows Auth Failed | Your credentials may be expired or incorrect. Click Edit, re-enter your credentials, and save. |
Discover Tools finds 0 tools | Make sure your MCP server implements the |
Server not appearing in the tool picker | Check that the server is enabled, has a "Connected" status, and has at least one discovered tool. |
Feature tab not visible | Custom MCP Servers may not be enabled for your account yet. Contact your administrator or Ally MSP. |
Limitations
Custom MCP Servers have the following constraints:
Tool selection limits:
Maximum 3 tools total (including both built-in Hatz tools and custom MCP tools) can be active in a single chat session
Network and accessibility:
Server URLs must be publicly accessible from the internet
Local URLs (such as
localhost,127.0.0.1, or private IP addresses) will not workThe server must not be behind a firewall or VPN that blocks inbound traffic from Hatz
Authentication:
OAuth authentication is not yet available (coming soon)
Only API Key, Bearer Token, and None authentication methods are currently supported
Transport protocol:
Only Streamable HTTP transport is supported at this time
Other MCP transport protocols (such as stdio) are not compatible with custom MCP servers in Hatz
Feature availability:
Custom MCP Servers must be enabled for your account by an administrator
Not all accounts or plans may have access to this feature
MCP server requirements:
Your server must properly implement the Model Context Protocol specification
The server must implement the
tools/listmethod to expose tools to Hatz
Why stdio MCP servers are not supported
Hatz does not support stdio-based MCP servers because they are incompatible with web applications. Stdio servers must run locally on your own machine and cannot be accessed remotely over the internet.
If you have an stdio MCP server that you want to use with Hatz, you will need to use a third-party service that hosts your stdio server and exposes it as an HTTP-based MCP server. Hatz does not provide this hosting or conversion service.
Note: Hatz Support is not able to help establish connections to stdio-based servers or assist with third-party hosting setup. For questions about converting your stdio server to HTTP, consult the documentation for your MCP server or the third-party hosting service you choose.
Based on the MCP registry and real-world examples, here are practical Streamable HTTP examples for your customers:
Real-World Examples of Streamable HTTP MCP Servers
To help you understand what types of services work well as custom MCP servers, here are some real-world examples of Streamable HTTP MCP servers:
These are hosted services you can connect to directly via their HTTP endpoints:
Business & Marketing:
Fiber.ai - Search companies, enrich contacts, and reveal emails and phone numbers
DataMerge - B2B data enrichment for 375M+ companies
Rolli - Social media search and analytics across X, Reddit, Bluesky, YouTube
Development & Integration:
Salesforce MCP - Comprehensive Salesforce administration and data management
LinkedIn API - Retrieve profile data and publish content via LinkedIn
GitHub/Bitbucket MCP - Manage repositories, pull requests, comments, and pipelines
Specialized Services:
MailJunky - Send emails, track events, and manage contacts
FileGraph - Extract text from documents, manipulate PDFs, perform OCR
FAQ
Q: What is MCP?
MCP (Model Context Protocol) is an open standard for connecting AI assistants to external tools and data sources. Any service that implements the MCP specification can be connected to Hatz as a custom server. Learn more at modelcontextprotocol.io.
Q: Are my credentials safe?
Yes. Credentials are encrypted and stored in a dedicated secure vault. They are never displayed in the UI after the initial save, and are only used server-side when connecting to your MCP server.
Q: Can I connect a server running on my local machine?
No. The server URL must be publicly reachable from the internet. Local URLs (like localhost or private IPs) will not work.
Q: How many custom MCP servers can I add?
There is no hard limit on the number of servers you can add. However, you can only select up to 3 tools at a time in a single chat (this includes both built-in and custom MCP tools).
Q: What transport protocols are supported?
Custom MCP servers use Streamable HTTP transport by default, which is the recommended MCP transport for remote servers. Other transport protocols are not currently supported.