Connect your agent

Apothicon is a local stdio MCP server. Your AI client starts the server process and calls its tools. It opens no network listener and needs no API key, embedding model, external database or running game to start.

Use the companion

Open Apothicon from the Start menu after installing, or run Start-Apothicon.cmd from the extracted source package. Save your workspace and installation settings, then visit Connections.

Select your installed client and use Connect, or Copy setup where that client needs manual configuration. The list includes Codex, Claude Code, Antigravity, Cursor, Gemini CLI, OpenCode, Copilot and other supported integrations. A greyed-out connection means detection did not find the client; its information icon explains the result. Refresh detection checks again without installing or launching anything.

The companion preserves unrelated settings and servers. Before changing an existing configuration file, it saves a backup beside it using the suffix .apothicon-backup-<sha256-prefix>. Repeating an unchanged connection does not rewrite the file. A foreign server already named apothicon must be renamed before Apothicon can register itself.

Sign in through the AI client’s normal interface. Apothicon configures the server connection and does not manage client accounts.

Start a new session

After connecting or changing settings, start a new agent session so the client launches the server with the current configuration. You can close the companion while the client uses the server.

Use Test MCP connection for a real transport check. It starts the local server, initializes MCP, lists tools and calls the read-only workspace_status tool. A passing probe confirms that local exchange; check the client’s own MCP status to confirm your signed-in session has loaded it too.

Try this first request:

Use Apothicon to inspect my workspace and Mod Tools installation. Discover the available capabilities, then explain what I can author and what is still needed before a native build.

Manual registration

Copy configuration exports the selected client’s format. Use absolute executable and configuration paths. A generic JSON registration is:

{
  "mcpServers": {
    "apothicon": {
      "command": "D:\\Projects\\apothicon-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "apothicon_mcp",
        "--config",
        "D:\\Projects\\apothicon-mcp\\apothicon.toml",
        "serve"
      ]
    }
  }
}

The outer format differs between clients. Codex uses [mcp_servers.apothicon] in ~/.codex/config.toml; Cursor uses mcpServers.apothicon in ~/.cursor/mcp.json; Gemini CLI uses ~/.gemini/settings.json. Prefer the companion’s export when you are unsure which format or profile your client uses.

For clients with a tool-count limit, add --tool-profile, compact before serve in the launch arguments. The optional compact profile exposes essential tools plus invoke_tool; discovery still returns schemas for the full registry.

Check from the console

From the project directory, these commands use the same setup and probe paths:

uv run apothicon-mcp --config apothicon.toml clients
uv run apothicon-mcp --config apothicon.toml connect codex
uv run apothicon-mcp --config apothicon.toml probe

If the connection fails, check the setup diagnostics. Once it responds, give the agent a map brief.