AGE MCP Server

An MCP server for querying Apache AGE graphs in PostgreSQL.

Version 0.3.0 makes read-only operation the secure default, adds asynchronous connection pooling, safe Cypher parameters and bounded cursor pagination, and returns MCP structured content from every tool.

Requirements

• Python 3.13 or later
• PostgreSQL with the Apache AGE extension installed and loaded
• A database role restricted to the graphs and operations the MCP client needs

Enable AGE in the target database:

CREATE EXTENSION IF NOT EXISTS age CASCADE;

Install

With uv:

uv init your_project
cd your_project
uv add age_mcp_server

With a Python virtual environment:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install age_mcp_server

With Homebrew:

brew install rioriost/tap/age_mcp_server

Configure an MCP client

Avoid placing a database password in command-line arguments. Supply a connection string through PG_CONNECTION_STRING and use one of libpq’s credential mechanisms, such as PGPASSWORD or a protected PostgreSQL password file.

{
  "mcpServers": {
    "age_manager": {
      "command": "age_mcp_server",
      "env": {
        "PG_CONNECTION_STRING": "host=db.example port=5432 dbname=postgres user=age_reader sslmode=require",
        "PGPASSWORD": "replace-with-a-secret"
      }
    }
  }
}

Treat the MCP client configuration as a secret if it contains PGPASSWORD. A PostgreSQL password file or the client’s secret store is preferable.

The connection string can still be supplied explicitly when necessary:

age_mcp_server --pg-con-str "host=db.example dbname=postgres user=age_reader sslmode=require"

For Microsoft Entra authentication to Azure Database for PostgreSQL, first sign in with the Azure CLI, then opt in to token acquisition:

age_mcp_server \
  --pg-con-str "host=server.postgres.database.azure.com dbname=postgres user=identity sslmode=require" \
  --azure-identity

Tools

Read-only mode is the default:

Write tools are only advertised and accepted when the server starts with --allow-write:

age_mcp_server --allow-write

Use a separate, least-privileged database role for write mode. Enabling the flag does not grant PostgreSQL privileges that the configured role does not already have.

Safety limits