How Do You Organise Custom API Tools Into Branded Connectors in Macha?

To organise custom API tools in Macha, put them in a tool group: give the group a name, an emoji or uploaded square icon, and a brand colour, and it shows up as a custom connector on the Connectors page next to native integrations like Zendesk, Shopify, and Stripe. Instead of a flat heap of endpoints, you get recognisable connectors: "Returns Service" in your brand teal, "Loyalty API" with the loyalty logo, "Internal Orders" in your company purple. Below is how it works, when the AI Tool Builder does the grouping for you, and where the feature has rough edges worth knowing about.

A quick framing note: Macha is the AI agent layer that sits on top of the help desk you already run (Zendesk, Freshdesk, Gorgias, Front, HubSpot or Intercom). Custom API tools and connector groups are how you extend those agents to reach systems Macha doesn't have a native integration for: your own backend, a niche SaaS, an internal microservice.

What is a connector group in Macha?

In Macha, a connector is the unit you see on the Connectors page. Native integrations (Zendesk, Stripe, Notion, Shopify, Google Workspace and the rest) each show up as one connector tile, and clicking in reveals the individual tools (search tickets, issue a refund, read a page) that integration provides.

A tool group makes your custom API tools behave the same way. Rather than every endpoint floating loose, you bundle related tools under one named connector with:

• a name (e.g. "Returns Service")
• a custom icon (an emoji, or a square logo you upload by clicking the group icon on the Custom Tools page)
• a brand colour

That connector then renders on the Connectors page next to the native ones, and the tools inside it are assigned to agents the same way as native tools. The grouping is purely organisational. It doesn't change what a tool does or how it authenticates, but at any real scale, organisation is the difference between a tool library you can reason about and one you're afraid to touch.

This shipped in the April 9, 2026 release, alongside the broader Custom API Tools and AI Tool Builder work: "Tool groups: Organize tools under named connectors with custom icons and brand colors. Groups appear on the connectors page."

Why does grouping custom tools matter?

Grouping looks cosmetic until you're the third person to inherit an agent configuration. Here's what the named-connector model buys you in practice:

• Findability. When you're assigning tools to an agent, you scan by connector ("everything under Loyalty API") instead of hunting individual endpoint names. Branded icons and colours make a connector recognisable at a glance, the same reason your IDE colour-codes file types.
• Mental model = source system. Tools are most useful when they map to the system they call. Grouping them under "Internal Orders" tells the next engineer (and the next agent-builder) exactly which backend a tool touches, without reading the URL.
• Cleaner agent configs. An agent that needs your returns flow gets the "Returns Service" tools as a coherent set. Reviewing what an agent can do becomes a connector-level question, not a forensic audit of twenty tool names.
• It scales. Twenty loose tools is unreadable. Twenty tools across four branded connectors is four things you can hold in your head.

This is the same problem the wider integration-platform market is trying to solve. Composio, StackOne, Paragon and Nango all organise their hundreds of pre-built connectors into browsable catalogs. Macha's angle is narrower and more practical for a support team: the connector you build lives inside the same Connectors page as your real integrations, not in a separate developer catalog. Your custom "Returns Service" sits next to Zendesk, and an agent treats both the same way.

How do you create a connector group by hand?

You can build a connector group by hand when you want full control. The flow, end to end:

1. Define the tool. On the Custom Tools page, click New tool and point it at a REST endpoint: pick the HTTP method (GET/POST/PUT/PATCH/DELETE), set URL parameters and a body template, set the tool's type to Read or Write, and choose authentication: none, API key, bearer token, or basic auth. Credentials are encrypted at rest and never exposed to the AI model.
2. Assign it to a tool group. Give the group a name, an emoji, and a brand colour, or drop the tool into a group you already created. New tools for the same system go into the same connector.
3. Test before you ship. Open the tool's edit modal, enter sample parameter values and press Test to fire a real request, then confirm the auth and response shape before any agent touches it.
4. Assign to agents. Grouped tools appear on the agent's Tools tab alongside built-in connector tools, ready to attach.

One safety default worth calling out: Write tools need confirmation. A tool typed as Write (anything that creates, updates, or deletes data) requires user confirmation before it runs in chat, so an agent can't silently change your system on a whim. When you build tools by hand, you set that type yourself, so mark every POST, PUT, PATCH, or DELETE tool as Write. That behaviour is independent of grouping, which means a connector full of write tools is governed the same careful way whether you grouped it or not.

Can the AI Tool Builder create the group for you?

Yes, and it's the faster path. The AI Tool Builder (shipped March 30, refined April 9, and currently offered through Macha Experiment Labs) starts from a Build with AI button on the Custom Tools page. You describe the API you want to connect and paste credentials; it discovers endpoints, tests the credentials, and proposes a set of tools. Review and confirm, and the tools are created and grouped automatically: "Tools are automatically grouped under a named connector with emoji icon and brand color."

So when you describe, say, your shipping provider's API, Macha doesn't dump six loose tools into your list. It stands up a single named connector with a sensible emoji and colour and files the tools underneath. Auth captured from a successful test request gets applied to every tool in the session, and write-method endpoints are marked for confirmation. The builder is conversational, so you can ask it to add endpoints or change groupings as you go. It works best when you give it the API documentation URL or a few example endpoints.

In practice the AI builder does most of the work and you tidy the rest: rename the connector to match your internal vocabulary, swap the auto-chosen emoji for your real logo, nudge the colour. That edit-after model is the right one. Let the machine do the discovery grind, and keep human judgement on the labels people will actually read.

How do agents use grouped tools?

Grouping pays off most at assignment time. When you open an agent's Tools tab, custom connectors appear alongside native ones, and you pick tools by connector. An agent can only use tools that have been explicitly assigned to it. An agent that handles returns gets the Returns Service connector's tools as a set; a WISMO ("where is my order") agent gets your Internal Orders tools. The agent then calls them exactly as it calls a native Zendesk or Shopify tool. The grouping is invisible at runtime and only affects how you manage the surface area.

Because grouped custom tools are first-class, everything else in Macha treats them normally: they stream as tool cards in autonomous conversations (with success/error results), they show in the "Tools Used" popup on saved messages, and they respect the same write-confirmation guardrails. A branded connector isn't a second-class citizen; it's a native integration you happened to build yourself. If you're new to wiring agents to systems, the custom tools docs cover the full setup.

When should you not bother with connector groups?

Connector groups are low-risk, but a few honest caveats:

• Grouping is organisation, not isolation. Putting tools in a connector doesn't sandbox their permissions or credentials; it's a label and a visual bucket. Security still lives at the tool level (the auth you configured and the Read/Write type) and the agent level (which tools you assigned). Don't treat a connector boundary as a permission boundary.
• The AI builder's naming is a starting point. Auto-chosen emojis and colours are fine defaults, but they're guesses. If three connectors all land on a generic gear emoji, the visual benefit evaporates. Take the ten seconds to differentiate them.
• You may not need custom tools at all. Custom API tools are included on Macha's one plan at every ticket volume, so there's no tier to move to for them. But if your whole workflow runs on native integrations, you may never need a custom connector. See the pricing page for what the plan includes.
• Don't over-group. If you have three custom tools total, one connector is plenty; four connectors of one tool each is clutter with extra clicks. Grouping earns its keep once a system owns several endpoints.

The honest summary: this is a quality-of-life feature. It doesn't make your agents able to do anything new; it makes the things they can do legible to the humans maintaining them. For a one-person setup that's a nicety; for a team that inherits each other's agents, it's the difference between a maintainable system and a write-only one.

Where do connector groups fit in Macha's tool setup?

Connector groups are the tidy front end of a deeper capability: turning any REST API into agent tools without writing an integration from scratch. The native integrations cover the common commerce, knowledge, and comms systems; custom API tools cover everything else; and branded connector groups make your custom work look and behave like the native connectors. The result is a single Connectors page that represents your whole agent surface area, native and bespoke alike.

If you've been putting off connecting an internal system because you dreaded the resulting tool sprawl, this feature removes the excuse.

FAQ

What is a tool group in Macha? A tool group is a named connector that bundles your custom API tools under one tile, with an emoji or uploaded icon and a brand colour, on the Connectors page, so they're organised like native integrations.

Do I have to create groups manually? No. The AI Tool Builder auto-groups tools it creates under a named connector with an emoji icon and brand colour. You can rename, re-icon, and recolour afterwards, or build groups by hand for full control.

Does grouping change what a tool can do or how it's secured? No. Grouping is organisational. Authentication is configured per tool (API key, bearer token, or basic auth, encrypted at rest), and tools typed as Write still require confirmation in chat regardless of which connector they sit in.

Can agents use grouped custom tools the same as native ones? Yes. Grouped custom tools appear on the agent's Tools tab alongside built-in connector tools and are called the same way at runtime.

Which plans include custom API tools and connector groups? All of them. Macha has one plan with every feature, priced by how many tickets a month you want handled, from $299 a month for 750 tickets. See the pricing page.

Can I upload my own logo for a connector? Yes. Click the group icon on the Custom Tools page to upload a custom square icon in place of the emoji.

How do you try connector groups?

If your agents need to reach a system Macha doesn't natively integrate, build the tools, group them under a branded connector, and they'll sit next to Zendesk and Shopify on your Connectors page. Start a free trial ($50 of usage, no credit card required, no time limit), or read more on the custom API tools page and the blog for related deep-dives.

Written by Abbas (Customer Support & AI, Macha) · Reviewed by Ankeet Guha (Co-founder & CTO) · Published 2026-06-24 · Last updated 2026-09-24.