# How to Set Up a Graphify HTTP Server for Teams

> Set up a Graphify HTTP server for teams easily. Learn how to enable team-wide access to knowledge graphs using the graphify-mcp CLI and a Starlette ASGI server.

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

---

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

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

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

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

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

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

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

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

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