# How to Access the codebase-memory-mcp API: Local HTTP Interface Guide

> Learn to access the codebase-memory-mcp API via its local HTTP interface. This guide explains how to use JSON endpoints for repository introspection and indexing with any HTTP client.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: how-to-guide
- Published: 2026-07-27

---

**The codebase-memory-mcp API is a localhost-only HTTP server that exposes JSON endpoints under `/api/` for repository introspection, background indexing, and graph visualization, accessible via any standard HTTP client once the daemon is running.**

The `codebase-memory-mcp` repository provides a lightweight HTTP interface for programmatic interaction with its Model Context Protocol (MCP) services. This local API allows external tools, scripts, and the built-in graph UI to query repository metadata, trigger indexing jobs, and retrieve graph layouts without requiring direct library integration.

## Starting the API Server

The API becomes available after launching either the background daemon or the interactive UI. Both commands initialize the HTTP listener on the configured port.

Start the service using the CLI:

```bash
codebase-memory-mcp daemon   # Background server only

codebase-memory-mcp ui       # Launches UI with API auto-enabled

```

The server configuration resides in `${CBM_CACHE_DIR:-~/.cache/codebase-memory-mcp}/config.json`. By default, the API listens on port **9749**, though this is configurable via the `ui_port` setting. Verify the active port by inspecting the configuration file:

```bash
cat "${XDG_CACHE_HOME:-$HOME/.cache}/codebase-memory-mcp/config.json"

# Output: { "ui_enabled": true, "ui_port": 9749 }

```

## API Architecture and Components

The HTTP layer consists of two distinct C modules in the `src/ui/` directory.

**HTTP Transport ([`src/ui/httpd.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/httpd.c))** implements a single-threaded HTTP/1.1 listener that binds exclusively to the loopback interface. This module handles raw socket operations, request parsing with strict CRLF validation, and enforces request size limits. The `socket_set_nonblocking` logic and bind operations occur at lines 44-48, ensuring the server only accepts localhost connections.

**Routing and Handlers ([`src/ui/http_server.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/http_server.c))** registers the concrete API endpoints and builds JSON responses. This file contains the dispatch logic for all `/api/*` routes and delegates work to core MCP services including the store, watcher, git integration, and indexing engine. The routing table comment at the top of the file documents the endpoint structure:

```c
/* Transport (sockets, parsing, limits) lives in httpd.c; this file owns
 * the routes and their handlers:
 *   GET /             → embedded index.html
 *   GET /assets/...   → embedded JS/CSS
 *   POST /rpc         → JSON-RPC dispatch
 *   OPTIONS /rpc      → CORS pre-flight
 *   GET/POST /api/... → UI support endpoints (layout, index, browse, …)
 *   *                 → 404
 */

```

## Core API Endpoints

All public endpoints are prefixed with `/api/` and return JSON responses. The following handlers are implemented in [`src/ui/http_server.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/http_server.c):

- **`GET /api/repo-info?project=NAME`** – Returns repository metadata including root path, current git branch, credential-stripped remote URL, and web-base URL for GitHub linking. Implemented in `handle_repo_info` (lines 27-44).

- **`GET /api/logs?lines=N`** – Retrieves the last *N* internal log lines (default 100). Implemented in `handle_logs` (lines 70-84).

- **`GET /api/processes`** – Lists running `codebase-memory-mcp` processes with PID, memory, CPU, and command details. Implemented in `handle_processes` (lines 33-57).

- **`GET /api/browse?path=DIR`** – Returns a JSON list of subdirectories for file-picker UI components. Implemented in `handle_browse` (lines 40-71).

- **`GET /api/adr?project=NAME`** – Reads an Architecture Decision Record (ADR) for a specified project. Implemented in `handle_adr_get` (lines 34-44).

- **`POST /api/adr`** – Saves an ADR with a JSON body `{ "project":"…","content":"…" }`. Implemented in `handle_adr_save` (lines 93-118).

- **`POST /api/index`** – Initiates a background indexing job with body `{ "root_path":"…","project_name":"…" }`. Implemented in `handle_index_start` (lines 100-124).

- **`GET /api/index-status`** – Returns the status of all indexing slots. Implemented in `handle_index_status` (lines 84-100).

- **`GET /api/project-health?name=NAME`** – Provides health metrics including node/edge counts and database size. Implemented in `handle_project_health` (lines 64-78).

- **`GET /api/layout?project=NAME&max_nodes=…&graph=…`** – Computes a 3-D layout for project visualization. Implemented in `handle_layout` (lines 115-135).

## Querying the API with HTTP Clients

Once the server is running, access the codebase-memory-mcp API using any HTTP client. The server enforces a **1 MiB** maximum body size (`MAX_BODY_SIZE` in [`http_server.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/http_server.c)).

Using `curl` to fetch repository information:

```bash
curl -s "http://127.0.0.1:9749/api/repo-info?project=myproj"

```

Example response:

```json
{
  "root_path": "/home/user/src/myproj",
  "branch": "main",
  "remote_url": "git@github.com:DeusData/myproj.git",
  "web_base": "https://github.com/DeusData/myproj",
  "blob_base": "https://github.com/DeusData/myproj/blob/main"
}

```

Python example using the `requests` library:

```python
import requests

BASE = "http://127.0.0.1:9749"
params = {"project": "myproj"}

resp = requests.get(f"{BASE}/api/repo-info", params=params)
data = resp.json()
print(data["web_base"])  # https://github.com/DeusData/myproj

```

## Triggering Background Jobs

The API supports asynchronous operations such as code indexing. To start indexing a new directory:

```bash
curl -X POST -H "Content-Type: application/json" \
     -d '{"root_path":"/home/user/src/otherproj","project_name":"otherproj"}' \
     http://127.0.0.1:9749/api/index

```

The response indicates the allocated slot and status:

```json
{"status":"indexing","slot":0,"path":"/home/user/src/otherproj"}

```

Monitor progress via the status endpoint:

```bash
curl http://127.0.0.1:9749/api/index-status

```

This returns an array of objects with fields `slot`, `status`, `path`, and `error`, where `status` may be `"indexing"`, `"done"`, or `"error"`.

## Security Model and Restrictions

The codebase-memory-mcp API implements several security controls to prevent unauthorized remote access.

**Localhost Binding**: The server explicitly binds to `127.0.0.1` only, as enforced in [`src/ui/httpd.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/httpd.c) lines 44-48. This prevents exposure to external network interfaces.

**CORS Protection**: The `update_cors` function (lines 96-110 in [`src/ui/http_server.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/http_server.c)) generates CORS headers that reject any origin not matching the exact localhost address. This protects against cross-site request forgery from malicious web pages.

**Credential Sanitization**: When returning git remote URLs, the API strips authentication credentials via `cbm_ui_git_strip_credentials` (lines 34-53) to prevent accidental exposure of private access tokens in API responses.

## Summary

- The codebase-memory-mcp API runs on **localhost only** (127.0.0.1) with a default port of **9749**, configurable via the JSON config file.
- The HTTP stack consists of [`src/ui/httpd.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/httpd.c) (transport layer) and [`src/ui/http_server.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/http_server.c) (routing and JSON handlers).
- Endpoints follow RESTful patterns: **GET** for reads (repo-info, logs, status) and **POST** for actions (indexing, saving ADRs).
- Request bodies are limited to **1 MiB**, and all responses include strict CORS headers preventing remote web access.
- Core functions like `handle_repo_info`, `handle_index_start`, and `handle_layout` provide programmatic access to the MCP store and indexing services.

## Frequently Asked Questions

### What port does the codebase-memory-mcp API use by default?

The API defaults to port **9749**, defined in the `ui_port` field of the configuration file located at `${CBM_CACHE_DIR:-~/.cache/codebase-memory-mcp}/config.json`. You can modify this setting before starting the daemon or UI to avoid conflicts with other local services.

### Is the codebase-memory-mcp API accessible from remote machines?

No. The server explicitly binds to the loopback interface (`127.0.0.1`) in [`src/ui/httpd.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/httpd.c) and cannot accept connections from external IP addresses. Additionally, CORS headers generated by the `update_cors` function reject cross-origin requests, ensuring only local clients can interact with the API.

### How do I trigger a code indexing job via the API?

Send a **POST** request to `/api/index` with a JSON body containing `root_path` and `project_name`. The `handle_index_start` function (lines 100-124 in [`src/ui/http_server.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/http_server.c)) queues the job and returns a slot identifier. Poll `/api/index-status` to monitor completion status, which indicates whether the job is `"indexing"`, `"done"`, or `"error"`.

### What security measures protect sensitive data in API responses?

The API strips credentials from git remote URLs using `cbm_ui_git_strip_credentials` before including them in JSON responses. All endpoints enforce a **1 MiB** body size limit (`MAX_BODY_SIZE`), and the CORS policy restricts requests to the same localhost origin, preventing credential leakage to malicious websites.