Assistant Core
Tools and MCP

Connect local tools with a local connector

Connect MCP servers on your own computer or private network through a connector that dials out, with no public URL or open port.

A local connector lets the assistant use tools that run on your computer or private network. The connector runs next to your MCP servers and opens a WebSocket connection out to Assistant Core, and the assistant calls the tools over that connection. No public URL or open port is needed.

For a complete example, see mcp-bash: a connector plus an MCP server that lets the assistant run bash commands on your machine. Read Keep the connector token secret before you run it.

Remote server or local connector?

Both are on the MCP page of the Admin Panel.

Remote servers tab (MCP Server)Local connector tab
Assistant Core calls your server's URLYour connector connects to Assistant Core
The server needs a public HTTPS URLThe server can sit behind NAT or a firewall, or run locally over stdio
Authenticated with OAuth, a token or a keyAuthenticated with a secret token per connector

Prerequisites

  • The Assistant Owner role. An Assistant Admin can view the connectors and tools but not change them.
  • A machine that can open an outbound connection to wss://api.assistantcore.com.

Connect a connector

  1. Open the Admin Panel and select the assistant.

  2. Go to MCP → Local connector and turn on Enable local connectors.

  3. Under Connectors, enter a Connector name for the machine (for example web01) and click Add Connector.

  4. Copy the connector settings right away. The token is shown only once.

  5. Run your connector with those settings, for example with mcp-bash:

    export LOCAL_CONNECTOR_URL="wss://api.assistantcore.com/local-connector/ws"
export LOCAL_CONNECTOR_TOKEN="lc_..."
python connector.py

    A connector of your own dials LOCAL_CONNECTOR_URL with the header Authorization: Bearer <token>, then answers MCP requests (JSON-RPC, one message per WebSocket frame) from your MCP server.

  6. Back in the Admin Panel, click Refresh Tools. The tools appear under Available Tools, with the connector each one comes from.

  7. Turn off the tools the assistant doesn't need, and set Available in for the rest.

If the tab says Local connectors are unavailable, the platform operator has not set them up yet.

Refresh approves the tools

The assistant uses a connector's tools exactly as they were when you last clicked Refresh Tools. If a connector adds a tool, or changes a tool's description, parameters or surfaces, that tool is held back until you refresh again, so a connector can't change a tool behind your back.

Refresh after you add a connector, update an MCP server or change a tool. A connector that is offline when you refresh keeps the tools you approved earlier. Refreshing also records each tool's readOnlyHint, destructiveHint and shell_argument, which decide whether its calls ask for approval.

Several machines

Add one connector per machine, up to 20 per assistant. Each has its own token, so you can regenerate or delete one without touching the others.

  • A token connects one machine at a time. A second connection with the same token is refused, so a leaked token can't take over a machine that is online.
  • A tool name belongs to the connector that offered it first. Another connector offering the same name is refused, and its log says so. Give each machine distinct tool names, for example web01_bash and db01_bash.
  • A token belongs to one assistant. To connect one machine to several assistants, run one connector per assistant, each with that assistant's token.

Keep the connector token secret

A connector token is a credential. Anyone with it can offer tools to the assistant and receive its tool calls and their arguments.

  • Don't commit the token to git or paste it anywhere public.
  • If a token leaks or is lost, click Regenerate Token on that connector. The old token stops working immediately and that connector is disconnected until you update it; the others keep working.
  • Click Delete Connector to disconnect it for good.

If a connector exposes tools that run shell commands or touch files, the assistant can act on that machine for whoever chats with it. Use it only with assistants whose users you trust, run the connector under a low-privilege account, keep the tool to the App surface, and turn off tools you don't need. Approval rules can then allow safe commands such as git status without allowing the whole tool: see Shell command rules.

No tools showing?

  • Check that Enable local connectors is on and the connector is listed under Connectors.
  • Check that the connector is running with its current token. Old tokens are rejected after you regenerate.
  • Check the connector's log: a refused connection says why (token already in use, or a tool name another connector offers).
  • Click Refresh Tools: new or changed tools are held back until you do.

Tool approvals

Allow safe commands and block risky ones.

MCP Server

Connect a server that has a public URL.

Last updated on

Connect an MCP server

Connect a remote MCP server by URL, sign in with OAuth or a key, and choose which of its tools the assistant can use.

Device tools

How an ESP32 device offers its own tools, such as volume, screen brightness or a camera, to the assistant during a voice session.

On this page

Remote server or local connector?PrerequisitesConnect a connectorRefresh approves the toolsSeveral machinesKeep the connector token secretNo tools showing?