AGE

AGE MCP Server enables you to run and manage the AGE graph interface with Azure-based PostgreSQL instances. It provides a way to start and control the MCP bridge between AGE graph extensions and your client tools, enabling graph queries and write operations when you opt in. This guide walks you through practical usage, installation, and configuration so you can connect your MCP client to your AGE-enabled Postgres server with confidence.

How to use

You use an MCP client to communicate with AGE MCP Server. Start the MCP server in stdio mode, pointing it at your PostgreSQL connection string, then connect your MCP client to the running server. If you need to enable write operations, activate the appropriate flag when starting the server. Ensure your PostgreSQL user has permission to access the database and the AGE extension is loaded on the server.

How to install

Prerequisites you need before installation:

• Python 3.13 and above
• This module runs on psycopg
• Enable the AGE extension in your Azure Database for PostgreSQL instance by ensuring the azure.extensions and shared_preload_libraries parameters include AGE
• Load the AGE extension in your PostgreSQL database with:
• CREATE EXTENSION IF NOT EXISTS age CASCADE;

Choose one of the installation methods below and follow the steps in order.

# Brew installation (macOS)
brew tap rioriost/age-mcp-server
brew install age-mcp-server

# uv-based setup (macOS/Linux/Windows)
uv init your_project
cd your_project
uv venv
source .venv/bin/activate
uv add age-mcp-server

# Python virtual environment (macOS/Linux)
mkdir your_project
cd your_project
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install age-mcp-server

# Python virtual environment (Windows)
mkdir your_project
cd your_project
python -m venv venv
.\venv\Scripts\activate
python -m pip install age-mcp-server

Usage with configuration examples

Use these MCP configurations to run AGE MCP Server with your preferred tool. Each example shows how to start the server with a PostgreSQL connection string. Replace the placeholder values with your actual server details.

{
  "mcpServers": {
    "age-manager": {
      "command": "age-mcp-server",
      "args": [
        "--pg-con-str",
        "host=your_server.postgres.database.azure.com port=5432 dbname=postgres user=your_username password=your_password",
      ]
    }
  }
}

Additional usage with the UV tool

If you prefer to run through the UV (Python virtual environment) tool, use the following configuration. This keeps your project isolated and allows you to wire in the MCP server execution under UV’s management.

{
  "mcpServers": {
    "age-manager": {
      "command": "/Users/your_username/.local/bin/uv",
      "args": [
        "--directory",
        "/path/to/your_project",
        "run",
        "age-mcp-server",
        "--pg-con-str",
        "host=your_server.postgres.database.azure.com port=5432 dbname=postgres user=your_username password=your_password",
      ]
    }
  }
}

Security and write operations

AGE MCP Server disables write operations by default for safety. If you need to enable writing to your AGE graph, add the --allow-write flag to the startup command.

{
  "mcpServers": {
    "age-manager": {
      "command": "age-mcp-server",
      "args": [
        "--pg-con-str",
        "host=your_server.postgres.database.azure.com port=5432 dbname=postgres user=your_username password=your_password",
        "--allow-write"
      ]
    }
  }
}

Notes on configuration and connections

The connection string includes host, port, database name, username, and password. For security, avoid hard-coding passwords in files. Consider using environment variables or a secure secret store for your production setup.

Release notes and maintenance

This MCP server has a history of updates focused on dependency management and security improvements. Regularly review release notes for new features, bug fixes, and security patches.

Troubleshooting tips

If the MCP server fails to start, verify that the PostgreSQL connection string is correct and that the AGE extension is loaded on the target database. Check that the AGE extension is enabled in the Azure Database for PostgreSQL server parameters and that the shared_preload_libraries includes age. Ensure the PostgreSQL user has sufficient privileges to access the database.

For more information

Access relevant AGE resources for broader graph capabilities on PostgreSQL, including guides for loading extensions and configuring AGE on Azure PostgreSQL.