Connections and integrations

Connections let Headmaster work with the apps and services you already use. This page covers every kind of connection: apps (connectors), custom tool servers (MCP), tools and skills, plugins, and messaging apps.

The big picture

On its own, the agent has built-in tools such as files, terminal, web and memory. Connections add more:

Kind	What it adds	Where to set it up
Connectors	Your apps, like a code host or task tracker, as tools the agent can call	Desktop: Skills → Connectors. Web: Settings → Integrations
Custom MCP servers	Any tool server you point Headmaster at	Desktop: Skills → Connectors → Add your own
Tools	Turn built-in tool groups on or off	Desktop: Skills → Tools
Skills	Packaged know-how for specific jobs	Desktop: Skills → Skills. Web: Skills in the sidebar
Plugins	Extensions for the agent and the app	Desktop: Skills → Plugins
Messaging	Reach your agent from Telegram, Slack and more	Desktop, Work mode: Skills → Messaging

In the desktop app, Skills in the sidebar opens a page with tabs: Skills, Tools, Connectors, Plugins, Messaging and Artifacts.

What is MCP?

MCP (Model Context Protocol) is an open standard for giving AI agents tools. An MCP server is a small program or web service that tells the agent "here are my tools, here is what each one does". Most connectors in Headmaster are MCP servers. You do not need to know the details to use them, but it helps when you add your own.

Connecting is always optional

The agent only uses apps you connect. Only authorize the apps you want Headmaster to use. You can turn any app off, or turn off single tools inside an app, at any time.

Connectors in the desktop app

Open Skills in the sidebar, then the Connectors tab.

The connectors page

Search finds an app by name. Category filters by type.
The segments All, Available, Connected and Turned off narrow the list.
Connected apps are at the top, with broken connections first so you notice them.
Turned off apps keep their sign-ins, so you can turn them back on without signing in again.

Kinds of connectors

Each card shows a small label saying what kind of connector it is:

Label	What it means
Managed	Hosted for you by Headmaster. You sign in with the app in your browser. Managed apps follow your account. Needs you to be signed in.
MCP · Catalog	A server from the Headmaster catalog that runs on this computer.
MCP · Custom	A server you added yourself.
MCP · Plugin	A server that came with a plugin you installed.

A card may also say Cloud runtime or Work runtime to show which mode it belongs to, or Runs inside the runtime when the server is set up inside your agent's workspace.

Connecting a managed app

Find the app and choose Connect.
Your browser opens the app's sign-in page. Sign in and approve access.
Back in Headmaster, the card changes to Connected.

If it says Waiting for your browser, finish the sign-in in your browser. If you closed it, choose Open the link again. To give up, choose Stop waiting.

Connector states

State	Meaning	What to do
Connected	Working.	Nothing.
Connecting	Starting up or signing in.	Wait a moment.
Access expired	The app's sign-in ran out.	Choose Reconnect.
Could not connect	The connection failed.	Choose Try again.
Needs authentication	A server needs you to sign in.	Choose Authenticate.
Error	The server refused the connection.	Open its logs from Advanced, or remove and add it again.
On, unused	Turned on, but no tools are on.	Turn on the tools you want.
Off	Turned off by you.	Choose Turn back on.

Choosing which tools an app may use

Open a connected app to see What Headmaster may do with it. Every tool is listed with a switch and a label for its effect:

Label	Meaning
Read	Reads data out of the app. It changes nothing.
Write	Creates or changes something in the app.
Destructive	Can remove something for good.
Unknown effect	The app never said what this tool does.

Smaller hints such as Creates, Updates, Deletes, Repeatable and External add detail.

Quick buttons set many tools at once:

Read only turns on reading tools and turns off the rest.
Turn off destructive keeps everything except tools that can delete for good.
Everything on turns on every tool.

Choose Save changes when you are done, or Discard to undo. Fewer tools also means less for the model to read on every call, so turning off tools you never use can make replies faster.

Disconnecting

Open the app and choose Disconnect. Headmaster stops acting as that account. You can connect again at any time. If you only want a break, use the switch to turn the app off instead. That keeps the sign-in.

Adding your own MCP server (desktop)

If the app you want is not in the list, you can point Headmaster at any MCP server.

On the Connectors tab, choose Add your own.
Paste a command or a config snippet into Paste a command or a snippet. Headmaster fills in the fields for you. If it cannot read it, fill in the fields by hand.
Give the server a Name.
Choose a Type and fill in its fields:

Type	Use it when	Fields
STDIO	The server is a program that runs on this computer	Command to launch, Arguments, Environment variables, Working directory
Streamable HTTP	The server is a web address	URL, Headers, Auth: None, OAuth or Bearer token

Save. The server's tools appear once it connects.

A custom server is one new entry in a settings file on this device. Choose Edit mcp.json if you prefer to edit that file directly. Removing a server only removes its entry. Nothing else is deleted.

Example: a local files server

Paste this into the snippet box:

npx -y @modelcontextprotocol/server-filesystem C:\Users\you\Documents\notes

Headmaster reads it as a STDIO server with the command and arguments filled in. Name it notes and save. The agent can now use its tools on that folder.

Example: a hosted server with a token

Choose Streamable HTTP, enter the server's URL, set Auth to Bearer token and paste the token the service gave you. Save, then open the server to choose which tools to allow.

Install links

Some websites offer a link that adds an MCP server to Headmaster. When you open one, Headmaster shows Add MCP server? with the exact configuration from the link. Nothing is saved until you choose Add server. If the server runs a program on your computer, you see an extra warning. Only continue if you trust the source.

Safety for custom servers

A STDIO server runs a program on your computer with your permissions. Only add servers you trust.
Prefer turning on Read only first, then add write tools as you need them.
If the same app is connected both as a managed app and as a local server, Headmaster warns that it sees every tool twice. Turn one of them off.

Connecting apps from a chat

You do not always have to visit the connectors page. If a task needs an app you have not connected, the agent can show a card in the chat:

Connect your apps lists the apps it needs, each with a Connect button. Choose Not now to skip.
Add MCP servers, Enable MCP servers or Authorize MCP servers cards appear when it needs a server installed, turned on or signed in.

Approve only what you want. The agent cannot connect anything without you.

Integrations in web chat

In web chat, open Settings → Integrations.

Connected apps lists what you have connected, each with its state.
Apps you can connect is the vetted catalog. Use Search apps to find one, then Connect or Set up.
Add your own lets you add any app by its web address. Only apps served over https can be connected. Choose how it signs you in: No sign-in, Sign in with the app, API key or Access token. Choose Check to test it.

Web chat only supports remote apps, that is, apps reached over the internet. It cannot run programs on your computer. Apps marked Managed for you and Runs in the cloud are hosted by Headmaster.

When you choose Sign in, a sign-in window opens. If your browser blocks it, you see "Your browser blocked the sign-in window." Choose Open the sign-in page instead. If it takes too long, try again.

To remove an app, choose Disconnect. Headmaster will no longer be able to use it. You can connect it again later.

Tools

Open Skills → Tools in the desktop app. Tools are grouped into toolsets, such as files, terminal and web.

Turn a toolset on or off with its switch.
Some toolsets show Needs keys until you add the key they need.
Sort by Most used to spot ones you never use, then use Disable unused.
Enable all and Disable all change every toolset at once.

Changes apply to new chats. A chat that is already open keeps the tools it started with.

Skills

A skill is packaged know-how: instructions and helpers for a specific kind of job. The agent loads a skill when a task matches it.

Each skill shows where it came from:

Source	Meaning
Built-in	Ships with Headmaster.
Hub	Installed from the skills hub.
Learned	Written by the agent from your own work, so it can repeat a job the same way next time.

In the desktop app, open Skills → Skills to search, turn skills on or off, read what each one does, edit it, or Archive it. Archived skills can be restored. Browse the hub from the same tab to install more. Changes apply to new chats.

In web chat, open Skills in the sidebar. Skills marked Needs setup need a key or sign-in before they work. Enabled skills are ready to use in your chats.

Plugins

Plugins extend Headmaster. A plugin can have two halves, each with its own switch:

Agent: adds tools, hooks or providers to the agent.
Desktop: adds features to the app itself.

Open Skills → Plugins in the desktop app. Use Browse to open the Plugin catalog and install a reviewed plugin with one click. Agent plugins take effect after the agent restarts.

Messaging apps

You can talk to your agent from a messaging app. Messages you send there reach your agent, and its replies come back in the same app. Scheduled tasks can also post results there.

Messaging runs in Work mode on the desktop app. In Cloud mode the page says it is not available in Cloud yet.

Open Skills → Messaging in the desktop app. Each platform shows a state: Needs setup, Connected, Connecting, Disabled, Restart needed or Error.

Supported platforms

Platform	How it connects
Telegram	A bot you create with BotFather, or the quick QR setup
Discord	A bot from the Discord Developer Portal
Slack	A Slack app using Socket Mode, with a bot token and an app token
WhatsApp	A bundled bridge with QR sign-in
Email	A dedicated IMAP and SMTP mailbox
SMS	Twilio
iMessage	Through Photon's Spectrum platform
Webhook	Other tools, like GitHub, send events over HTTP
A2A	Other agents reach Headmaster over the Agent2Agent protocol

Each platform has Open setup guide, which opens the provider's own setup page, and a short note on how to get your credentials.

Setting one up

Choose the platform.
Follow Get your credentials and paste the values into the Required fields. Recommended and Advanced fields are optional.
Turn the platform on and choose Save changes.
If you see Restart needed, choose Restart now.

Credentials are saved only to this Headmaster installation.

Example: Telegram in two minutes

Open Skills → Messaging → Telegram.
Choose Create with QR under Quick setup.
Scan the QR code with Telegram on your phone and confirm. Headmaster creates the bot and detects your Telegram user ID.
Check Allowed users and choose Save and restart.
Message your new bot in Telegram.

Prefer to do it by hand? Create a bot with @BotFather, paste its token into Bot token, and add your numeric ID from @userinfobot to Allowed Telegram user IDs.

Who can talk to your agent

Always fill in the allowed users field. Without it, anyone who finds your bot could message your agent.

When someone new messages your bot, they can appear under Pending requests. Choose Approve to let them in, or ignore the request. Approved users lists everyone with access. Choose Revoke to remove someone. They stop being recognized on their next message. After too many failed approvals, a platform locks out for a while.

Worked example: an app plus a routine

Goal: every Monday, a summary of your open issues lands in Slack.

Connect your code host on the Connectors tab. Open it and choose Read only.
Set up Slack on the Messaging tab, in Work mode.
In a chat, ask: "Every Monday at 9am, list my open issues that have not changed in a week and send the list to Slack."
The agent creates a scheduled task. Check it under Tasks.

Troubleshooting

Problem	What to try
A connector says Access expired	Choose Reconnect and sign in again.
The sign-in did not finish	Choose Open the link again, finish in your browser, or Stop waiting and start over.
Managed apps are not available for this account yet	Managed apps need a signed-in account. Sign in, or add the app as your own server.
A custom server shows Error	Check the command or URL. Open Advanced to see its logs.
A new server's tools do not appear	Choose Refresh tools from the app's menu. Start a new chat.
The agent sees every tool twice	The same app is on as managed and local. Turn one off.
Messaging shows Restart needed	Choose Restart now.
Messaging is not available	Switch to Work mode. Messaging does not run in Cloud yet.
Web chat: the sign-in window does not open	Allow pop-ups for the site, or choose Open the sign-in page.
Web chat: "Only apps served over https can be connected"	Use the app's https address.