How to Set Up a Graphify HTTP Server for Teams

Graphify exposes knowledge graphs over HTTP via the graphify-mcp CLI, enabling team-wide access by running a Starlette-based ASGI server that supports configurable authentication, stateless operation, and both JSON and Server-Sent Events (SSE) response formats.

To set up a Graphify HTTP server for teams, you deploy the MCP (Message-Control-Protocol) transport layer implemented in the Graphify-Labs/graphify repository. The server implementation in graphify/serve.py transforms your local knowledge graph into a queryable HTTP endpoint that developers can access from any IDE, CI pipeline, or custom client across your network.

Prerequisites: Installing the MCP HTTP Transport

The HTTP server requires optional dependencies defined in pyproject.toml (lines 51–55). These include uvicorn and starlette>=1.3.1, which provide the ASGI server and application framework.

Install the MCP extras to enable HTTP transport:

pip install "graphify[mcp]"

This pulls in the required ASGI stack while keeping the base Graphify package lightweight for offline graph construction workflows.

Starting the HTTP Server for Team Access

The entry point for the HTTP server is the graphify-mcp CLI, which delegates to the serve_http function in graphify/serve.py (lines 1749–1765). This function orchestrates graph loading, ASGI app construction, and the uvicorn server startup.

Binding to Public Interfaces

By default, the server binds to 127.0.0.1 for local development. For team-wide access, bind to 0.0.0.0 using the --host argument (defined in lines 52–56) and specify a port with --port:

graphify-mcp \
  --transport http \
  --host 0.0.0.0 \
  --port 8080 \
  --api-key team-secret-key

This configuration makes the server accessible to all machines on your local network.

Customizing the Mount Path

The default endpoint mounts at /mcp. Change this using the --path argument (lines 57–61) to avoid collisions with existing services:

graphify-mcp --transport http --path /graph-mcp --port 8080

Securing Your Graphify HTTP Server

When exposing the server to team networks, always configure authentication to prevent unauthorized graph access.

API Key Authentication

The server supports header-based authentication via the --api-key argument or the GRAPHIFY_API_KEY environment variable (lines 66–70). Clients must provide the key in one of two headers:

• Authorization: Bearer <key>
• X-API-Key: <key>

If you bind to 0.0.0.0 without specifying an API key, the server emits a security warning (lines 1798–1802) because the graph becomes publicly accessible to anyone on the network.

Start a secure server for production team use:

export GRAPHIFY_API_KEY="secure-random-string"
graphify-mcp \
  --transport http \
  --host 0.0.0.0 \
  --port 8080 \
  --stateless

Advanced Configuration Options

Stateless Operation for Load Balancing

For CI environments or containerized deployments behind load balancers, enable --stateless mode (lines 67–70). This flag disables per-session state management, allowing multiple server instances to handle requests without shared session storage:

graphify-mcp \
  --transport http \
  --host 0.0.0.0 \
  --port 8080 \
  --stateless \
  --api-key ci-key

JSON vs SSE Responses

By default, the server streams responses using Server-Sent Events (SSE). For simpler client integration, force plain JSON responses using the --json-response flag (lines 63–66):

graphify-mcp --transport http --json-response --port 8080

Session Timeout Management

Control idle-session reclamation with the --session-timeout flag (lines 71–74), which defaults to 3600 seconds. Lower this value in high-turnover environments to free resources quickly:

graphify-mcp --transport http --session-timeout 300

Architecture and Implementation Details

The serve_http function (lines 1749–1765) performs three critical operations:

1. Graph Loading: Calls _load_graph to read graph.json, enforce size limits, and apply learning overlays.
2. ASGI Construction: Invokes _build_http_app to create a Starlette application routing the configured --path to the _MCPASGIApp handler.
3. Server Execution: Hands the ASGI app to uvicorn (lines 1730–1748) for HTTP request handling.

When the server starts, it prints the binding address and authentication status:

graphify MCP server (streamable-http) on http://0.0.0.0:8080/mcp - auth required

Client Integration Example

Query the server from Python using standard HTTP requests:

import requests

API_KEY = "team-secret-key"
BASE_URL = "http://server-ip:8080/mcp"

def query_graph(target):
    headers = {"Authorization": f"Bearer {API_KEY}"}
    payload = {"type": "lookup", "target": target}
    
    response = requests.post(
        BASE_URL, 
        json=payload, 
        headers=headers, 
        timeout=10
    )
    return response.json()

# Query from any team member's workstation

result = query_graph("my_function")
print(result)

Summary

• Installation: Install graphify[mcp] to obtain uvicorn and starlette>=1.3.1 dependencies.
• Team Access: Use --host 0.0.0.0 to expose the server on your network, configured in graphify/serve.py (lines 52–56).
• Security: Always set --api-key or GRAPHIFY_API_KEY when binding to public interfaces; the server warns against unauthenticated public exposure (lines 1798–1802).
• Stateless Mode: Enable --stateless for horizontal scaling and containerized deployments.
• Response Formats: Choose between default SSE streaming or --json-response for stateless request-response patterns.
• Core Implementation: The serve_http function (lines 1749–1765) in graphify/serve.py orchestrates the Starlette ASGI app and uvicorn server lifecycle.

Frequently Asked Questions

What is the default host and port for the Graphify HTTP server?

The server defaults to 127.0.0.1 (localhost) on port 8080, as defined in the argument parser at lines 52–56 of graphify/serve.py. For team access, you must explicitly set --host 0.0.0.0 to accept connections from remote machines.

How do I secure the server for production team use?

Always specify an API key using either the --api-key argument or the GRAPHIFY_API_KEY environment variable. According to the source code at lines 66–70, the server validates the Authorization: Bearer <key> or X-API-Key: <key> headers. The server explicitly warns (lines 1798–1802) if you start on a public interface without authentication.

Can I run Graphify in a containerized or load-balanced environment?

Yes. Enable --stateless mode (lines 67–70) to disable per-session state, allowing multiple container instances to handle requests independently without requiring shared session storage. This configuration is ideal for Kubernetes deployments or CI runners.

What is the difference between JSON and SSE response modes?

By default, the server streams Server-Sent Events (SSE), which maintains a persistent connection for real-time updates. When you pass --json-response (lines 63–66), the server returns plain JSON responses instead, which simplifies integration with standard HTTP clients that do not support SSE parsing.

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