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

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:

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:

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

/* 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:

• 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).

Using curl to fetch repository information:

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

Example response:

{
  "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:

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:

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:

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

Monitor progress via the status endpoint:

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 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) 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 (transport layer) and 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 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) 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.

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