Components

AsanagiDB-mcp

The MCP (Model Context Protocol) server. Bridges AI tools — Claude, Gemini, Cursor, any MCP-capable client — to the AsanagiDB graph store. Runs locally on 127.0.0.1 by default. Supports federated deployment via --central (client) and --public (server) modes, both secured with automatic mTLS.

Modes

Local

Default mode. AI tools on the same machine connect to 127.0.0.1. No certs, no config.

--central

Connect this MCP instance to a remote central server. mTLS certs auto-provisioned via Sigil on first run.

--public

Run as a federation server on 0.0.0.0. Requires mTLS — refuses to start without certs. Server-to-server only; AI tools never connect here directly.

Quick Start

# local mode — AI tools point to http://localhost:8080
asanagidb-mcp

# connect to a central (remote) MCP server — Developer license required
asanagidb-mcp --central tcp://10.0.0.1:8443

# run as a federation server — mTLS is mandatory
asanagidb-mcp --public --http-port 8443

Flags

--http-port <port> HTTP port for local AI tool connections (default: 8080)

--db-name <name> Database name / tenant to connect to

--db-path <path> Path to the AsanagiDB Unix domain socket

--remote <path> Proxy to a standalone AsanagiDB engine daemon instead of a local database — UDS path or tcp://host:port (Developer license required for tcp://)

--central <tcp://host:port> Connect to a remote central MCP server (Developer license required)

--public Enable federation server mode on 0.0.0.0 (mTLS required)

--cert-dir <path> Directory for mTLS certs (default: ~/.Asanagi)

--sigil-url <url> Sigil endpoint for automatic cert provisioning

A Note on --remote

--remote is unrelated to federation — it proxies this MCP instance straight to a standalone AsanagiDB engine daemon over its own wire protocol, not to another AsanagiDB-mcp instance.

A Unix domain socket connection needs no TLS — it's local and filesystem-permission-scoped. A tcp:// connection is plaintext by design: AsanagiDB does not implement TLS for this link itself. We strongly recommend putting a TLS-terminating reverse proxy (e.g. Caddy) in front of the engine daemon's TCP port if it crosses an untrusted network — but it isn't required. If you're fine connecting over a trusted network, or just want to use a UDS path, that's a supported choice too.

Federation Architecture

AI Tool ──MCP (HTTP, plain)──► asanagidb-mcp (local, 127.0.0.1)
                                      │
                            --central tcp:// (mTLS)
                                      │
                                      ▼
                            asanagidb-mcp --public (remote MCP Server, 0.0.0.0)

AI tools never connect to a --public instance directly. The public port is server-to-server only, always mTLS.

Trust on this link comes from the mTLS client certificate and its Sigil-issued license binding, not from hostname matching — federation peers are known by license identity, not by DNS name, so the connection address is not checked against the certificate's subject.