Overview
========

The AgensGraph **Model Context Protocol (MCP)** servers expose
`AgensGraph <https://github.com/skaiworldwide-oss/agensgraph>`_ to MCP clients such as
`Claude Desktop <https://claude.ai/download>`_. They let an LLM agent query a graph,
keep a knowledge-graph memory, or design a graph schema — through standard MCP tools, with no
application code of your own.

There are three servers, built on `FastMCP <https://gofastmcp.com/>`_ 3 and the
`agensgraph-python <https://pypi.org/project/agensgraph-python/>`_ 2.0 driver:

.. list-table::
   :header-rows: 1
   :widths: 28 18 54

   * - Server
     - Needs a DB?
     - What it does
   * - ``mcp-agensgraph-cypher``
     - Yes
     - Run Cypher against a graph.
   * - ``mcp-agensgraph-memory``
     - Yes
     - A knowledge-graph memory an agent grows.
   * - ``mcp-agensgraph-data-modeling``
     - No
     - Design graph schemas and generate Cypher.

- ``mcp-agensgraph-cypher``: schema introspection, paginated reads, writes with stats, query
  plans, index advice, and health checks.
- ``mcp-agensgraph-memory``: the memory holds entities, relations and observations.
- ``mcp-agensgraph-data-modeling``: generates the constraint + ingest Cypher.

A shared ``mcp-agensgraph-common`` core provides their configuration, connection pooling,
statement policy, transports, and result handling.

.. note::

   **The servers are pure tools — they call no LLM and need no API key.** The intelligence
   comes from the MCP client (e.g. Claude Desktop) that *uses* the tools. That also makes
   them easy to test with a script or the MCP Inspector.

**Key features**

- **Paginated reads** (``limit`` / ``offset`` / ``has_more`` / ``next_offset``) and a token
  budget on every read response, so an unbounded query can't flood the client's context.
- **Read-only safety**: reads run inside a ``READ ONLY`` transaction, so the database refuses a
  write whatever the text looked like, and a server-wide read-only mode does not register the
  write tool at all.
- **Graph statements only**: each tool takes one graph statement. SQL, including SQL behind
  ``EXPLAIN``, is refused, and changing a graph's shape needs ``--allow-graph-ddl``.
- **No privileged roles**: a server refuses to start as a superuser or a member of
  ``pg_execute_server_program``, since ``COPY ... TO PROGRAM`` would get past a read-only
  transaction, unless ``--allow-server-programs`` accepts it.
- **Namespacing** so several servers (e.g. one per graph) can run side by side with
  prefixed tool names.
- **Multiple transports**: ``stdio`` (default) and Streamable ``http`` (with CORS and
  DNS-rebinding protection); ``sse`` is supported but deprecated.

.. note::

   **Version 0.3.1.** The three servers and the shared core (``mcp-agensgraph-common``) are
   published to PyPI at ``0.3.1``. An MCP client launches them with ``uvx``, for example
   ``uvx mcp-agensgraph-cypher``; ``pip install "agensgraph-ai[mcp]"`` installs all three for
   hosting them yourself (see :doc:`installation`). They require Python 3.11 or later; the
   Cypher and memory servers also need AgensGraph 2.17 or later.