---
owner: gmikcon
status: active
last_reviewed: 2026-05-11
review_interval: 30d
confidence: high
source_of_truth: repository
---

# Agent MCP Usage

This document explains what the Gnexus Book MCP server is for and how an AI agent should use it.

## Purpose

Gnexus Book is the canonical knowledge base for the owner's digital and server infrastructure.

The MCP server is the agent-facing interface to that knowledge base. It lets an agent read and maintain documentation without knowing the repository layout, raw REST API, or Git workflow.

The MCP server is valuable because it gives agents:

- stable access to canonical Markdown documentation;
- structured YAML inventory for hosts, services, domains, networks, endpoints, projects, databases, backups, hardware, and virtual machines;
- relationship graph data across inventory records;
- freshness and validation checks;
- controlled write operations through pending changes, validation, and local Git commits.

## Proactive Usage Rule

Agents should not wait for the user to explicitly say "look in the knowledge base".

If a task mentions or depends on the owner's infrastructure, the agent should consult Gnexus Book proactively before giving a confident answer or making changes.

Use MCP proactively for questions about:

- hosts, servers, VPS, VMs, hardware, routers, or local devices;
- IP addresses, domains, ports, routes, VPNs, proxies, nginx upstreams, or network topology;
- deployed services, web applications, smart-home components, GitBucket repositories, or project ownership;
- whether something is local, VPN-only, public, stale, undocumented, or dependent on another component;
- where a project is hosted, deployed, or documented;
- what an agent should update after discovering new infrastructure facts.

## When Not To Use It

Do not use MCP for unrelated general knowledge.

Do not use MCP to store secrets. Raw passwords, access tokens, private keys, recovery codes, session cookies, and secret config values must not be written to documentation or pending changes.

It is acceptable to document non-secret operational identifiers:

- hostnames;
- usernames;
- internal and public IP addresses;
- domains;
- ports;
- credential references such as `owner-managed` or `ssh-key`;
- access model notes such as `auth required` or `read-only SSH key`.

## Read Workflow

Start broad, then narrow.

1. Use `search_docs(query)` for natural-language lookup.
2. Use `read_doc(path)` for canonical narrative context.
3. Use `list_inventory(inventory_type)` for structured records.
4. Use `get_inventory_item(inventory_type, item_id)` when the id is known.
5. Use `get_relationships()` when dependencies, routes, upstreams, domains, or unresolved references matter.
6. Use `check_freshness()` when deciding whether documentation may be stale.
7. Use `validate_repository()` before trusting the repository state for maintenance work.

Examples:

- For `git.gnexus.space`, search docs for `git.gnexus.space`, then inspect `domains`, `services`, `endpoints`, and relationships.
- For `smart-home-server`, read the server and automation docs, then inspect `hosts`, `hardware`, `services`, `databases`, and `backups`.
- For a repository question, read the GitBucket catalog first and pay attention to last commit dates.

## Write Workflow

Documentation writes should be factual, focused, and committed.

For non-trivial changes:

1. Use `propose_doc_change` or `propose_inventory_item_change`.
2. Use `apply_pending_change`.
3. Use `validate_repository`.
4. Use `commit_changes`.

For simple full-document changes, `update_doc` can create the pending change, apply it, validate it, and commit it in one operation.

Every write should include:

- a short `summary`;
- a clear `reason`;
- no raw secrets;
- `last_reviewed` updates only when the agent actually verified the fact.

## Interpreting Repository Activity

For GitBucket repositories, last commit date matters.

Default interpretation:

- repositories touched in 2026 are potentially active;
- repositories last touched in 2025 are dormant unless deployment evidence says otherwise;
- repositories last touched in 2024 are old/archive candidates until confirmed.

Do not call a repository active only because it exists in GitBucket.

## Conflict Handling

If live observations and documentation disagree:

- say what conflicts;
- prefer live observations for immediate operational decisions;
- update Gnexus Book with the new fact if it is relevant and safe to document;
- keep uncertainty explicit with `confidence`, notes, or discovery-observation docs.

## Agent Prompt Guidance

When this MCP server is listed in an agent's available tools, the agent should treat it as infrastructure memory.

A good system prompt rule is:

> Before answering infrastructure-specific questions or making infrastructure-related changes, consult Gnexus Book MCP proactively. Use it to verify documented facts, discover relationships, and update documentation after new facts are found.