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

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, which loads a pre-generated 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, 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) 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 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 before starting the API server.

Stdio Transport (Default for Local Assistants)

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

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:

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:

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:

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:

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:

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 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, 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 changes.
• LLM backend selection for semantic queries is handled in 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, 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). 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 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. 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).

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