How to Start the Graphify MCP Stdio Server

Install the optional [mcp] extra (pip install "graphify[mcp]"), then run graphify-mcp ./graphify-out or graphify ./graphify-out --mcp to launch the stdio server that exposes your knowledge graph to AI agents via JSON-RPC over standard input/output streams.

The Graphify MCP (Model Context Protocol) stdio server enables AI agents like Claude to query your knowledge graphs through standard input/output streams. This guide explains how to launch the server using the Graphify-Labs/graphify codebase, referencing the actual implementation in graphify/serve.py and the CLI entry points defined in graphify/cli.py.

Prerequisites

Install the MCP Extra

The stdio server code resides in the optional [mcp] dependency group and is not included in the base installation. Install it using your preferred package manager:

# Using pip

pip install "graphify[mcp]"

# Using uv (recommended)

uv tool install "graphify[mcp]"

This installation registers the graphify-mcp console script entry point, which provides a direct shortcut to start the server without typing the full graphify command with flags.

Generate a Knowledge Graph

Before starting the server, you must generate a Graphify graph to a local directory. Run the standard ingestion command:

graphify <source> --out graphify-out

This creates the graph files under graphify-out/, which the MCP server will read from when processing queries.

Starting the Graphify MCP Stdio Server

You can start the server using two equivalent command patterns. Both invoke the same underlying code path in graphify/serve.py.

Option 1: Using the dedicated console script (recommended)

graphify-mcp ./graphify-out

Option 2: Using the full CLI with the --mcp flag

graphify ./graphify-out --mcp

Both commands dispatch to serve._run_mcp_stdio(graph_path) at approximately line 1592 in [graphify/serve.py](https://github.com/Graphify-Labs/graphify/blob/v8/graphify/serve.py). The process blocks indefinitely, waiting for JSON-encoded MCP requests on STDIN and writing responses to STDOUT.

How the Server Works Internally

When you invoke either start command, the execution flows through these components:

1. graphify/cli.py parses the --mcp flag and validates the graph path argument.
2. The CLI calls _run_mcp_stdio in graphify/serve.py, which initializes the low-level MCP manager.
3. The server enters an asyncio event loop that reads newline-delimited JSON messages from standard input.
4. For each valid request, the server executes graph operations (such as query_graph, get_node, or shortest_path) and returns JSON responses via standard output.

The implementation uses the stdio transport defined in the MCP specification, making it compatible with any MCP client that communicates over pipes.

Interacting with the Server

Once running, the server accepts JSON-RPC style messages. You can interact with it using shell commands or programmatically via subprocess.

Bash One-Liner

Send a request and parse the response using printf and jq:

printf '{"method":"get_node","params":{"node_id":"123"}}\n' | \
  graphify-mcp ./graphify-out | \
  jq .

Python Client Example

Launch the server as a subprocess and communicate via pipes:

import subprocess
import json

proc = subprocess.Popen(
    ["graphify-mcp", "./graphify-out"],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    text=True,
)

def mcp_call(method, **params):
    request = json.dumps({"method": method, "params": params})
    proc.stdin.write(request + "\n")
    proc.stdin.flush()
    response = proc.stdout.readline()
    return json.loads(response)

# Example: Query the graph

result = mcp_call("query_graph", query="node-name")
print(result)

Supported MCP Methods

The server exposes several graph operations that agents can invoke:

• query_graph – Execute semantic searches across the knowledge graph.
• get_node – Retrieve specific node details by ID.
• shortest_path – Calculate paths between nodes.

Each method expects a JSON object with method and params keys, and returns a JSON response object on the same stream.

Summary

• Install the [mcp] extra to access the graphify-mcp console script and graphify/serve.py implementations.
• Generate your graph first using graphify <source> --out graphify-out.
• Start the server with either graphify-mcp ./graphify-out or graphify ./graphify-out --mcp.
• Understand that the server runs via serve._run_mcp_stdio in graphify/serve.py, using an async loop over STDIN/STDOUT.
• Interact by sending newline-delimited JSON requests and reading JSON responses.

Frequently Asked Questions

What is the difference between graphify-mcp and graphify --mcp?

Both commands start the same stdio server, but graphify-mcp is a convenience console script installed by the [mcp] extra that directly invokes the server without requiring the --mcp flag. The graphify --mcp form uses the main CLI parser in graphify/cli.py to route to the same underlying serve._run_mcp_stdio function. Use graphify-mcp for shorter syntax when available.

Do I need to generate a graph before starting the server?

Yes. The server requires a pre-built graph directory (typically graphify-out/) created by running graphify <source> --out graphify-out. The MCP server reads from this directory to respond to queries; it does not perform ingestion on its own.

What MCP methods does the Graphify stdio server support?

According to the implementation in graphify/serve.py, the server supports methods including query_graph for semantic searches, get_node for retrieving node details, and shortest_path for pathfinding operations. Each method accepts parameters via the JSON-RPC params field and returns results as JSON objects.

How do I troubleshoot connection issues with the stdio server?

Ensure the graph path exists and contains valid Graphify output files. Verify that the [mcp] extra is installed by checking if graphify-mcp is in your PATH. The server communicates exclusively over STDIN/STDOUT, so ensure your client is not attempting HTTP connections. For debugging, run the server manually and send a simple {"method":"query_graph","params":{"query":"test"}} line to verify JSON responses appear on STDOUT.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}