Connect an assistant

Give an AI assistant the address of your Asterobot, with a password when you've set one, and check that it sees the tools.

Lire cette page en français

Connecting an assistant means giving it one address. Asterobot needs no setting for it: the endpoint is on as soon as Asterobot starts.

The address

The endpoint is /mcp on Asterobot's port, the one in server.listenAddress:

The assistant must run on the same computer as Asterobot, or reach it the way Asteroboard does from another device. An assistant that runs on a website rather than on your computer can't reach 127.0.0.1; see From another machine.

Claude Code

In a terminal, run:

claude mcp add --transport http asterobot http://127.0.0.1:8080/mcp

Then start a conversation and ask it something about Asterobot, such as "list my bots". The first time it uses a tool that changes something, it asks for your permission.

claude mcp list shows the servers it knows and whether it reaches them.

Other assistants

Every assistant that supports MCP over HTTP takes the same address, called the server's URL. Many read it from a JSON file with an entry like this one, under a name you choose:

{
  "mcpServers": {
    "asterobot": {
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

The exact file and its shape depend on the assistant, so check its documentation for "MCP" and "HTTP". Two things to know when it asks:

• The transport is HTTP, sometimes called streamable HTTP. It isn't the older SSE transport, and it isn't a command to run.
• Asterobot keeps no session between calls. Assistants built for the current version of the protocol work; a very old one that insists on a session id from the server won't connect.

With a password

When server.basicAuth holds a login and a password, /mcp requires them too, as an Authorization header. The value is Basic followed by the login, a colon and the password, encoded in base64. To encode alice:s3cret:

echo -n 'alice:s3cret' | base64

[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("alice:s3cret"))

Then give the assistant the header. With Claude Code:

claude mcp add --transport http asterobot http://127.0.0.1:8080/mcp --header "Authorization: Basic YWxpY2U6czNjcmV0"

Other assistants have a headers entry next to the URL in their configuration file.

From another machine

An assistant on another computer reaches Asterobot the way Asteroboard does from another device, and with the same care: Asterobot on a remote machine and Security apply word for word. An SSH tunnel is the simplest: it keeps Asterobot on 127.0.0.1 and the address stays http://127.0.0.1:8080/mcp on the machine where the assistant runs.

When Asterobot listens on a network address without basic auth, its console says so at start:

The MCP is reachable from the network without authentication: set server.basicAuth or listen on loopback

That is the same exposure Asteroboard already has in that setup, said out loud once.

Check that it works

When Asterobot starts, its console and terminal show one line about the endpoint:

Then ask the assistant to check that Asterobot answers: it has a tool for that, get-runtime-ping, whose answer is pong. If the assistant says it can't reach the server, check the address and the port, and that Asterobot is running.

Next: Tools, events and limits.