# How to Start the Graphify MCP Stdio Server

> Learn how to start the Graphify MCP stdio server to expose your knowledge graph to AI agents. Install the mcp extra and easily launch the server with simple commands.

- Repository: [Graphify Labs/graphify](https://github.com/Graphify-Labs/graphify)
- Tags: how-to-guide
- Published: 2026-07-16

---

**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`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/serve.py) and the CLI entry points defined in [`graphify/cli.py`](https://github.com/Graphify-Labs/graphify/blob/main/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:

```bash

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

```bash
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`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/serve.py).

**Option 1: Using the dedicated console script (recommended)**

```bash
graphify-mcp ./graphify-out

```

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

```bash
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/main/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`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/cli.py)** parses the `--mcp` flag and validates the graph path argument.
2. The CLI calls **`_run_mcp_stdio`** in [`graphify/serve.py`](https://github.com/Graphify-Labs/graphify/blob/main/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`:

```bash
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:

```python
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`](https://github.com/Graphify-Labs/graphify/blob/main/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`](https://github.com/Graphify-Labs/graphify/blob/main/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`](https://github.com/Graphify-Labs/graphify/blob/main/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`](https://github.com/Graphify-Labs/graphify/blob/main/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.