---
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.

At the beginning of an infrastructure-related task, agents should call `get_agent_usage_guide()` if they are not already familiar with this workflow.

## 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.

The default stance is: if the agent learns a durable, non-secret infrastructure fact that will be useful later, the agent should update Gnexus Book during the same task.

Durable facts include:

- a new or changed host, VM, VPS, router, device, or physical server;
- a new or changed IP address, hostname, MAC address, domain, port, route, upstream, VPN path, or network segment;
- a new or changed service, project, repository, deployment path, owner, version, status, or dependency;
- a live observation that contradicts existing documentation;
- a user-provided clarification that changes the meaning of existing docs;
- evidence that a project is active, dormant, abandoned, deployed, or no longer deployed.

Do not update the canonical docs for purely temporary observations unless they are useful as discovery notes. Use `90-maintenance/discovery-observations/` for scans, uncertain findings, or facts that should not yet become canonical inventory.

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.

If the agent decides not to update Gnexus Book after learning a relevant fact, it should state why. Acceptable reasons include:

- the fact is sensitive and would expose a secret;
- the fact is too temporary or uncertain;
- the user explicitly asked not to document it;
- the change requires a larger documentation pass and should be queued.

## Tool Selection

Use this decision table:

| Situation | Tool |
| --- | --- |
| Agent is unsure how to use this MCP server | `get_agent_usage_guide()` |
| Broad lookup by phrase or object name | `search_docs(query)` |
| Read canonical narrative docs | `read_doc(path)` |
| See available structured inventory types | `list_inventory()` |
| Read all records of one inventory type | `list_inventory(inventory_type)` |
| Read one known record | `get_inventory_item(inventory_type, item_id)` |
| Understand dependencies/routes/upstreams | `get_relationships()` |
| Check staleness | `check_freshness()` |
| Check repository safety before/after changes | `validate_repository()` |
| Create/update a Markdown page | `propose_doc_change()` then `apply_pending_change()` |
| Create/update structured YAML inventory | `propose_inventory_item_change()` then `apply_pending_change()` |
| Review local changes | `git_status()` and `git_diff()` |
| Commit validated changes | `commit_changes()` |
| Simple full-document replacement | `update_doc()` |

## End-Of-Task Checklist

Before finishing an infrastructure-related task, the agent should check:

- Did I learn a durable infrastructure fact?
- Did I discover a mismatch between live state and documentation?
- Did I add or update documentation/inventory?
- If not, did I explain why not?
- Did I run validation after changes?
- Did I create a local Git commit when changes were applied?

## 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.