Knowledge & tools

MCP servers

An MCP (Model Context Protocol) server is a remote service that publishes a set of tools. Connect one to your workspace and its tools become ordinary Hania tools, ready to assign to agents exactly like the built-in ones. It is a way to add new capabilities without waiting for Hania to build a dedicated integration for each service.

What an MCP server is

MCP is an open standard for offering tools to AI agents. A server publishes tools such as "search issues", "create a ticket", or "look up a customer", and any client that speaks the protocol can use them. When you connect a server, Hania reads the list of tools it offers and adds each one to your tools catalog. From that point on they behave like any other Hania tool: the agent decides when to call one based on the conversation, and you control how it runs.

You manage servers from MCP servers in the sidebar, under Build.

What Hania can connect to

Hania connects to remote servers that are reachable at a public https address and speak the Streamable HTTP transport. Most hosted MCP servers fit this description.

Local or "stdio" servers are not supported. These are the ones a desktop AI app launches as a command on your own computer, and they have no public address for Hania to reach. The endpoint also has to be a concrete URL: a server whose address still contains a placeholder you are meant to fill in cannot be connected. If you try either, the connection is refused with a message that only remote Streamable HTTP servers are supported, and nothing is saved.

Add a server from a template

Templates are a curated set of popular servers, shown as cards under Start from a template on the MCP servers page. You can search them and filter by category.

Pick a card and it prefills the connection form with the server's name, endpoint, and the right sign-in method, so you only confirm the details, add anything the server needs (a token, a sign-in, or a few header values), and connect.

The template gallery may be empty until an administrator adds entries for your workspace. When there are none, use the custom option below to add any server yourself.

Add a custom server

Choose Connect custom to enter a server by hand. You provide:

Name - a label for the server in your workspace.
Endpoint - the server's public https address.
Authentication - how Hania signs in (see below).

This is the "bring your own server" option, and it accepts any endpoint that meets the requirements above.

Choose how Hania signs in

Every server is connected with one of three sign-in methods:

Method	When to use it
None	The server is open and needs no credentials.
Bearer token	You paste a token or API key (for example a personal access token). It is stored securely, never shown again, and sent with every request.
OAuth	You sign in through the provider in your browser. See Connect an OAuth server.

Custom headers

Some servers need one or more extra headers on every request, in addition to (or instead of) a token. A common example is a server that needs both a token and an instance URL header. Where a template declares the headers a server needs, the form shows a labelled field for each one, with a short description and any hint the template provides. For a custom server, add them yourself with Add header.

You always type the header values in yourself at connect time. They are stored securely and are never shared with other workspaces.

Connect an OAuth server

Choose OAuth and connect. The server is saved and shown as Awaiting authorization. Use Authorize and Hania sends you to the provider's own sign-in page. Approve access there, and you return to the console. Once authorization succeeds the server becomes Active and its tools are pulled in.

Some providers need a pre-registered client. For a few providers (Google-based and GitHub-based servers are common examples), you first create an OAuth app in the provider's own developer console, then paste its client ID (and, for confidential clients, a client secret) into the connection form. This is because those providers do not register apps automatically. When it is required, the connect flow tells you so; reconnect with the client ID and secret filled in. The secret is stored securely and never shown again.

OAuth always includes a browser sign-in step, so an OAuth server cannot be connected purely through the API.

What happens when you connect

For None or a bearer token, Hania checks the server the moment you connect: it confirms the server is reachable and lists the tools it offers, so a working connection shows its tool count right away. If the endpoint is not a working remote MCP server, nothing is saved and you get the "remote Streamable HTTP only" message.

A few servers will list their tools without a credential but still require a sign-in to actually use them. If you try to add one of these as None, Hania refuses and asks you to connect with OAuth instead. This prevents a confusing state where tools appear but every call fails.

Use the tools with your agents

Each tool from a connected server appears in your tools catalog as an ordinary, assignable tool. You assign them to agents through the same flow as any other tool, with the same per-tool options: instructions for the agent, whether the agent speaks while the tool runs, whether it speaks after, and how tool errors are handled.

MCP tools are managed from the MCP servers area, not the generic "Add tool" form. In the tools catalog the MCP entry points you back here for adding, refreshing, or removing them.

Refresh or disconnect a server

A server's tools can change over time. Use Refresh tools on a server to pull its current list again. Do this after you finish an OAuth sign-in, or any time you want to pick up new tools the server has added.

Disconnecting a server is a clean removal, not a pause. It deletes that server's tools and removes them from every agent they were assigned to. If you reconnect the same server later its tools come back, but you will need to assign them to your agents again.

Plan limits

Your plan can cap how many MCP servers a workspace connects. If you are at the limit, adding another is refused with a message to upgrade. Remove a server you no longer need, or move to a higher plan. The calls your MCP tools make are metered as tool usage, the same as any other tool. See Plans & usage.

Common messages

You see	What it means and what to do
Only remote Streamable HTTP servers are supported	The endpoint is not a working remote MCP server, or it is a local/stdio one. Check that the URL is the server's public `https` address, and see What Hania can connect to.
Connect with OAuth instead	You chose None, but the server needs a sign-in to use its tools. Reconnect and choose OAuth.
Requires a pre-registered OAuth client	The provider needs an OAuth app that you create in its developer console. Create it, then reconnect with the client ID (and secret) filled in.
MCP server limit reached	Your workspace is at its plan's limit for connected servers. Disconnect one you no longer use, or upgrade your plan.