Skip to main content

Custom MCP Servers

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 must not be disabled by your workspace administrator (contact your administrator if you do not see the feature)

Getting Started

Where to find it

  1. Navigate to Workshop > Connections.

  2. If Custom MCP is available for your workspace, you will 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

  1. Click the Custom MCP Servers tab.

  2. Click Add Server (top-right corner, or the button in the empty state).

  3. 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., https://mcp.example.com/mcp).

Authentication Method

Yes

How Hatz should authenticate with your server (see Authentication Methods below).

  1. (Recommended) Click the Test button next to the URL field to verify the server is reachable before saving.

  2. 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 X-API-Key if left blank).

Bearer Token

The server expects a bearer token in the Authorization header.

A Bearer Token value.

OAuth

The server requires browser-based OAuth.

Use Auto-detect (DCR) if the server supports Dynamic Client Registration, or choose I have credentials and provide the OAuth Client ID and Client Secret from your app registration.

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.

OAuth redirect URI guidance

Some OAuth MCP providers require you to register a redirect URI, also called a callback URL, before Hatz can connect. For Hatz cloud, register this exact redirect URI with the provider: https://ai.hatz.ai/v1/connections/oauth-callback

The redirect URI must match exactly, including https, path, and trailing slash behavior. If the provider supports Dynamic Client Registration, Hatz may register the client automatically. If the provider does not support auto-registration, create the OAuth app in the provider first, add the redirect URI above, then choose I have credentials in Hatz and enter the Client ID and Client Secret.

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, or an OAuth server still needs browser authorization.

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:

  1. Open the tool picker in a chat or workflow.

  2. Your custom MCP servers appear alongside the built-in tools.

  3. Each server card shows the server name, tool count, and description (or URL).

  4. 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. For OAuth servers, confirm the provider has the Hatz redirect URI registered and then reconnect.

Discover Tools finds 0 tools

Make sure your MCP server implements the tools/list method and returns at least one tool.

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 be disabled for your workspace. Contact your workspace administrator or Ally MSP.

Error on initial connection

Some SaaS applications only make their MCP server available to specific AI tools and block access from all others. Check the vendors MCP documentation to confirm if any AI tool can connect to their hosted MCP server.

Unsupported integrations and request path

If an app such as Ninety.io, NetSuite, or another business system is not listed in the Hatz Connections catalog, check whether the vendor offers a hosted HTTP MCP server. If it does, and Custom MCP Servers are enabled for your workspace, you can try connecting it from Workshop > Connections > Custom MCP Servers.

If the vendor only offers a standard REST API, a local stdio MCP server, or no MCP-compatible endpoint, Hatz does not provide a generic API connector that can connect to it automatically. Submit or upvote the integration request on the Hatz feature request board, and include the vendor name, the workflow you want to automate, and whether the vendor has an API or MCP server.

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 work

  • The server must not be behind a firewall or VPN that blocks inbound traffic from Hatz

Authentication:

  • Supported methods are None, API Key, Bearer Token, and OAuth.

  • OAuth servers must support provider metadata discovery. Servers that do not support Dynamic Client Registration require you to provide OAuth client credentials from your provider-side app registration.

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 not be disabled for your workspace by an administrator

  • Some workspaces may have Custom MCP disabled by an administrator

MCP server requirements:

  • Your server must properly implement the Model Context Protocol specification

  • The server must implement the tools/list method 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.

Did this answer your question?