# How to Use the Graphify API: A Complete Guide to the MCP Server

> Learn how to use the Graphify API with our complete guide. Query nodes, traverse edges, and analyze code relationships using the MCP server and JSON-RPC.

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

---

**Graphify exposes its knowledge-graph functionality through a lightweight MCP (Model-Control-Protocol) server that supports both stdio and HTTP transports, allowing client-side LLMs or custom programs to query nodes, traverse edges, and analyze code relationships via JSON-RPC.**

The **Graphify API** provides programmatic access to code knowledge graphs built from your repositories. According to the Graphify-Labs/graphify source code, the entire API surface is implemented in [`graphify/serve.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/serve.py), which loads a pre-generated [`graph.json`](https://github.com/Graphify-Labs/graphify/blob/main/graph.json) file and exposes graph operations as RPC-style tools. This architecture enables integration with local developer assistants, CI pipelines, or shared team services.

## Understanding the Graphify API Architecture

The core API logic resides in **[`graphify/serve.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/serve.py)**, which implements an MCP server with three primary responsibilities: graph loading, tool registration, and transport handling.

**Graph Loading and Validation**
The `_load_graph` function (lines 22-33 in [`serve.py`](https://github.com/Graphify-Labs/graphify/blob/main/serve.py)) validates the supplied JSON, enforces size caps, and converts the data into a NetworkX graph. This ensures that only properly formed graphs extracted via `graphify extract …` are served.

**Tool Registration**
The server registers available tools through the `list_tools` coroutine (lines 1078-1083). These tools include `query_graph` for semantic searches, `get_node` for entity retrieval, `shortest_path` for relationship traversal, and `list_prs` for impact analysis.

**Transport and Authentication**
The server supports two transport modes selected via `--transport stdio|http` (argument parsing at lines 1060-1070). When running in HTTP mode, the server validates all requests against an API key provided via `Authorization: Bearer <key>` or `X-API-Key: <key>` headers (lines 66-73).

**LLM Backend Integration**
For graphs containing semantic data (docs, PDFs), the API respects the same backend configuration as the CLI. The [`graphify/llm.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/llm.py) module (lines 950-1005) handles backend selection (OpenAI, Anthropic, Gemini, Ollama) via environment variables, ensuring consistent behavior whether you are extracting or querying.

## Starting the Graphify MCP Server

You must first build a graph using `graphify extract …` to generate [`graphify-out/graph.json`](https://github.com/Graphify-Labs/graphify/blob/main/graphify-out/graph.json) before starting the API server.

**Stdio Transport (Default for Local Assistants)**

Use stdio mode when integrating with local Claude-style assistants or shell pipelines:

```bash
python -m graphify.serve graphify-out/graph.json \
    --transport stdio \
    --api-key "my-secret"

```

**HTTP Transport (For Team Services)**

Use HTTP mode to expose the Graphify API as a stand-alone service:

```bash
python -m graphify.serve graphify-out/graph.json \
    --transport http \
    --host 0.0.0.0 \
    --port 8080 \
    --api-key "$GRAPHIFY_API_KEY"

```

## Querying the Graph: API Examples

Once the server is running, you interact with the graph using JSON-RPC 2.0 requests.

**Query via cURL (HTTP Transport)**

Retrieve subgraphs based on natural language questions:

```bash
curl -X POST http://localhost:8080/mcp \
     -H "Authorization: Bearer $GRAPHIFY_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
          "jsonrpc":"2.0",
          "id":1,
          "method":"query_graph",
          "params":{"question":"what connects FastAPI to ModelField?"}
        }'

```

**Retrieve Specific Nodes**

Use `get_node` for IDE-like "go-to-definition" functionality:

```bash
curl -X POST http://localhost:8080/mcp \
     -H "Authorization: Bearer $GRAPHIFY_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":2,"method":"get_node","params":{"node_id":"FastAPI"}}'

```

**Python Client Integration**

Use the `mcp` library for structured Python access:

```python
from mcp import Client

client = Client("http://localhost:8080/mcp", api_key="my-secret")
response = client.call("query_graph", {"question": "explain RateLimiter"})
print(response)  # human-readable subgraph text

```

**Stdio Transport from Custom Scripts**

For subprocess-based integration without HTTP overhead:

```python
import subprocess, json, sys

proc = subprocess.Popen(
    ["python", "-m", "graphify.serve", "graphify-out/graph.json"],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    text=True,
)

request = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "shortest_path",
    "params": {"source": "FastAPI", "target": "ModelField"},
}
proc.stdin.write(json.dumps(request) + "\n")
proc.stdin.flush()

print(proc.stdout.readline())  # JSON-RPC response

proc.terminate()

```

## Advanced API Features

**Hot-Reload Capability**
The server caches graph contexts per file. If the underlying [`graph.json`](https://github.com/Graphify-Labs/graphify/blob/main/graph.json) changes (detected via mtime/size), the cache invalidates automatically and the graph reloads (lines 1048-1058). This keeps long-running API services synchronized with updated codebases without requiring restarts.

**Structured JSON Responses**
Add `--json-response` when starting the server to receive machine-parseable JSON instead of human-readable text, useful for downstream automation pipelines.

## Summary

- The **Graphify API** is implemented as an MCP server in [`graphify/serve.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/serve.py), exposing knowledge-graph operations via JSON-RPC.
- Supports **stdio transport** for local LLM assistants and **HTTP transport** for shared services, with Bearer token authentication required for HTTP.
- Core operations include `query_graph`, `get_node`, `shortest_path`, and `list_prs`, registered in `list_tools` (lines 1078-1083).
- Graph loading and validation occur in `_load_graph` (lines 22-33), converting JSON extracts into NetworkX graphs.
- **Hot-reload** functionality (lines 1048-1058) automatically updates the served graph when [`graphify-out/graph.json`](https://github.com/Graphify-Labs/graphify/blob/main/graphify-out/graph.json) changes.
- LLM backend selection for semantic queries is handled in [`graphify/llm.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/llm.py) (lines 950-1005), respecting environment variables for OpenAI, Anthropic, or local models.

## Frequently Asked Questions

### What transport protocol does the Graphify API use?

The Graphify API uses **MCP (Model-Control-Protocol)** over JSON-RPC 2.0. According to [`graphify/serve.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/serve.py), you can select between **stdio** (standard input/output) for local process communication or **HTTP** for network-accessible services using the `--transport` flag.

### How do I authenticate requests to the Graphify HTTP API?

All HTTP requests must include an API key in either the `Authorization: Bearer <key>` header or the `X-API-Key: <key>` header. The server validates this key before executing any tool, as implemented in the API-key handling logic (lines 66-73 of [`serve.py`](https://github.com/Graphify-Labs/graphify/blob/main/serve.py)). The key is set when starting the server via the `--api-key` argument.

### Can the Graphify API handle updates to the graph without restarting?

Yes. The server implements hot-reload functionality in the context loading logic (lines 1048-1058). It monitors the [`graph.json`](https://github.com/Graphify-Labs/graphify/blob/main/graph.json) file's modification time and size; when changes are detected, the cache invalidates and the graph reloads automatically. This is essential for CI pipelines or long-running development servers.

### What is the difference between `query_graph` and `get_node` tools?

**`query_graph`** performs semantic searches across the graph using natural language questions, leveraging LLM backends configured in [`graphify/llm.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/llm.py). **`get_node`** retrieves specific entity data by `node_id`, functioning like a symbol lookup or "go-to-definition" feature. Both are registered as available tools in `list_tools` (lines 1078-1083).