Getting Started

Remote Access

Run asanagidb on one machine and connect asanagidb-mcp to it from another — for example from inside a sandbox, VM or container.

Overview

AI tool ──► asanagidb-mcp --remote tcp://IP:PORT  (sandbox / other machine)
                              │  plaintext TCP
                              ▼
                       asanagidb  bind_address: reachable interface

This is the engine-daemon link described in A Note on --remote. It is separate from --central federation, which uses mTLS.

1. Server Config

The Homebrew install doesn't ship a config file. Create one anywhere and point --config at it. Use an absolute path.

# /etc/asanagi/config.yaml
defaults:
  bind_address: "192.168.1.20"   # the interface the MCP side can reach
  port: 8080

instances:
  default:
    data_dir: "/var/lib/asanagidb"

asanagidb --config /etc/asanagi/config.yaml

The default instance is used unless you pass --instance <name>. Keys accepted: bind_address, port, data_dir, uds_path, map_size, uds_mask, log_level, auth_enabled, tls_enabled, role, replication_port, leader_addr, on_promote. Values under defaults are inherited by every instance. TLS certificate and key paths aren't set in the file; they come from --tls-cert / --tls-key.

2. Connect asanagidb-mcp

asanagidb-mcp --remote tcp://192.168.1.20:8080

On start-up it logs a warning that the connection is plaintext. That's expected.

Requirements

Developer license

tcp:// needs a license with the remote_mcp capability (Developer or higher), read from ~/.asanagi/license.json or ./license.json on the machine running asanagidb-mcp. A Unix socket path needs no license, but a socket can't cross a VM or container boundary.

An IP address

The address after tcp:// must be an IP, not a hostname. Use tcp://192.168.1.20:8080, not tcp://dbhost:8080.

A reachable port

The server must listen on an address the MCP machine can reach. The default bind address is 127.0.0.1, which only accepts connections from the same machine.

Security

The --remote link is plaintext and doesn't log in: it sends an MCP hello, not credentials. Anyone who can reach the port can query the database.

Bind to the specific interface the other side uses rather than 0.0.0.0 where you can, and firewall the port to that machine's address.
To encrypt the link, put a TLS-terminating reverse proxy such as Caddy in front of the server's port.
Don't enable server-side TLS (--tls-cert) or auth_enabled on the listener that asanagidb-mcp --remote connects to: the MCP client speaks neither. The server also turns authentication on by itself once its default database has users.

Troubleshooting

requires a Developer license

asanagidb-mcp found no license, or the license has no remote_mcp capability. Check ~/.asanagi/license.json on the machine running asanagidb-mcp.

hostname resolution not yet supported; use an IP

Replace the hostname in tcp://host:port with its IP address.

Connection refused or timeout

The server is still bound to 127.0.0.1, a firewall is blocking the port, or the IP/port is wrong. Confirm with the server's startup log, which prints the address it is listening on.

Requests hang, server logs "Unauthorized request attempt"

auth_enabled is on for the server. asanagidb-mcp --remote doesn't log in, so its requests are rejected. Turn auth_enabled off for that instance, or give the MCP a separate instance.

Save failed: EndOfStream

The server is listening with TLS (--tls-cert/--tls-key) but asanagidb-mcp --remote connects in plaintext. Drop server TLS on that listener, or terminate TLS in a proxy such as Caddy.

No such file: config

A relative --config path is resolved against the current directory. Use an absolute path.