# Semantica CLI, REST API, and MCP Access Surfaces: A Complete Technical Guide

> Explore Semantica's CLI, REST API, and MCP access surfaces in this technical guide. Learn how to leverage Semantica's core functionality through multiple interfaces for seamless integration.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-09-12

---

**Semantica exposes its core functionality through three distinct access surfaces: a Click-based Command-Line Interface (CLI), a conventional HTTP REST API, and a JSON-RPC Model Context Protocol (MCP) interface.**

The [semantica-agi/semantica](https://github.com/semantica-agi/semantica) repository implements these entry points atop a unified execution engine, ensuring consistent behavior whether you invoke operations via terminal commands, HTTP requests, or programmatic RPC calls. Each access surface provides complete coverage of the platform's knowledge graph operations, ingestion pipelines, and decision engines while maintaining synchronized validation schemas.

## Command-Line Interface (CLI)

The **CLI** delivers a rich, typed command hierarchy built on the [Click](https://click.palletsprojects.com/) framework. Implemented in [`semantica/cli.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/cli.py), this surface defines a command group using `@click.group()` and nested subcommands such as `semantica kg`, `semantica ingest`, and `semantica shell`.

Click automatically generates help text, validates option types, and raises `click.ClickException` for user-friendly error reporting. The CLI interfaces directly with the core execution logic, avoiding HTTP serialization overhead for local operations.

```bash

# Show top-level help

semantica --help

# Ingest a folder of documents

semantica ingest /path/to/data --store memory

# Export the current graph to GraphML

semantica export_graph --format graphml > graph.graphml

```

Error handling occurs through Click's exception mechanism. Lines 28-31 in [`semantica/cli.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/cli.py) demonstrate how the CLI catches and formats exceptions into clean, readable messages before exiting.

## REST API

The **REST API** exposes conventional JSON-over-HTTP endpoints through an HTTP server defined in [`semantica_mcp/mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/server.py). This "Explorer" service provides synchronous access to the same internal core used by the CLI.

Key endpoints include `POST /api/v1/ingest` for document ingestion, `GET /api/v1/graph` for graph retrieval, and `POST /api/v1/decision` for decision engine queries. The server authenticates requests, validates payloads against the shared configuration schema, and returns standard HTTP status codes with JSON bodies.

```bash

# Ingest JSON documents via HTTP

curl -X POST http://localhost:8000/api/v1/ingest \
     -H "Content-Type: application/json" \
     -d '{"paths": ["data/*.json"]}'

# Retrieve the whole graph in RDF/Turtle

curl http://localhost:8000/api/v1/graph?format=turtle

```

The validation layer ensures that constraints remain identical across the REST API and CLI surfaces, preventing configuration drift between access methods.

## Model Context Protocol (MCP)

The **MCP** (Model Context Protocol) implements a JSON-RPC-style protocol supporting both **STDIO** transport for subprocess-based tooling and HTTP transport for network access. Protocol handling resides in [`semantica_mcp/mcp/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/__init__.py), while the server entry point in [`semantica_mcp/mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/server.py) hosts the endpoint.

MCP messages follow a strict JSON structure containing `method`, `params`, and `id` fields. The protocol exposes a catalog of tools—including `export_graph`, `semantic_retrieval`, and `decision`—with individual implementations located in `semantica_mcp/mcp/tools/`.

```python
from semantica.ingest.mcp_client import MCPClient

# Connect to an MCP server (HTTP or stdio)

client = MCPClient(url="http://localhost:8000/mcp")

# Invoke the `semantic_retrieval` tool

response = client.run_tool(
    "semantic_retrieval",
    {"query": "What are the main components of Semantica?"}
)

print(response["result"])

```

The `MCPClient` class serializes requests into JSON-RPC objects, transmits them through the selected transport mechanism, and parses structured JSON responses. This dual-transport capability allows integration with both local subprocesses and remote services.

## Shared Core Architecture

All three access surfaces interface with the same underlying execution engine defined in [`semantica/worker.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/worker.py). This shared core prevents code duplication and guarantees consistent behavior across terminal, HTTP, and JSON-RPC invocations.

The test suites validate this consistency across surfaces. [`tests/test_cli_commands.py`](https://github.com/semantica-agi/semantica/blob/main/tests/test_cli_commands.py) verifies that CLI commands properly raise `click.ClickException`, while [`tests/test_mcp_server_version.py`](https://github.com/semantica-agi/semantica/blob/main/tests/test_mcp_server_version.py) confirms that the MCP server returns correct version metadata.

## Summary

- **Three entry points** serve the Semantica platform: Click-based CLI, HTTP REST API, and JSON-RPC MCP interface.
- **CLI implementation** in [`semantica/cli.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/cli.py) leverages Click for command hierarchies, automatic help generation, and type validation.
- **REST endpoints** defined in [`semantica_mcp/mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/server.py) provide synchronous HTTP access to ingestion and graph operations.
- **MCP protocol** supports both STDIO and HTTP transports via [`semantica_mcp/mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/server.py), exposing tools like `semantic_retrieval` and `export_graph` through JSON-RPC.
- **Unified validation** ensures identical payload constraints across CLI and REST surfaces, with all routes converging on [`semantica/worker.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/worker.py).

## Frequently Asked Questions

### How does Semantica handle errors differently between the CLI and REST API?

The CLI raises `click.ClickException` instances that render human-readable messages to stderr, as implemented in [`semantica/cli.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/cli.py). The REST API returns standard HTTP status codes with JSON error bodies, while the MCP layer returns JSON-RPC error objects containing structured code and message fields.

### Can I use the MCP interface over standard input/output instead of HTTP?

Yes. The MCP implementation in [`semantica_mcp/mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/server.py) supports **STDIO** transport for subprocess-based integration, allowing external tools to spawn Semantica as a child process and communicate via stdin/stdout. This mode uses the same JSON-RPC framing as the HTTP variant but eliminates network overhead.

### Which access surface should I choose for batch processing large datasets?

For batch processing, use the **CLI** with commands like `semantica ingest` for direct filesystem access and local execution through [`semantica/worker.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/worker.py). The CLI avoids HTTP serialization overhead and provides progress indicators through Click's echo utilities.

### Are the validation schemas identical across all three access surfaces?

Yes. Both the CLI and REST API validate payloads against the same configuration schemas, ensuring that a request valid for `semantica ingest` will also pass validation when sent to `POST /api/v1/ingest`. The MCP layer maintains this consistency by routing to the same internal core functions used by the other surfaces.